diff options
| author | Karl Berry <karl@freefriends.org> | 2012-05-21 00:15:27 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2012-05-21 00:15:27 +0000 |
| commit | a4c42bfb2337d37da89d789cb8cc226367994e32 (patch) | |
| tree | c3eabdef5d565a4e515d2be0d9d4d0540bde0250 /Master/tlpkg/tlperl/lib/pods | |
| parent | 8274475057f024d35332ac47c2e2f23ea156e6ed (diff) | |
perl 5.14.2 from siep
git-svn-id: svn://tug.org/texlive/trunk@26525 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods')
141 files changed, 37575 insertions, 15511 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perl.pod b/Master/tlpkg/tlperl/lib/pods/perl.pod index e67f0627dea..29cabf1fc05 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl.pod @@ -1,6 +1,6 @@ =head1 NAME -perl - The Perl language interpreter +perl - The Perl 5 language interpreter =head1 SYNOPSIS @@ -78,6 +78,7 @@ For ease of access, the Perl manual has been split up into several sections. perlpacktut Perl pack() and unpack() tutorial perlpod Perl plain old documentation perlpodspec Perl plain old documentation format specification + perlpodstyle Perl POD style guide perlrun Perl execution and options perldiag Perl diagnostic messages perllexwarn Perl warnings and their control @@ -104,7 +105,7 @@ For ease of access, the Perl manual has been split up into several sections. perluniintro Perl Unicode introduction perlunicode Perl Unicode support perlunifaq Perl Unicode FAQ - perluniprops Index of Unicode Version 5.2.0 properties in Perl + perluniprops Index of Unicode Version 6.0.0 properties in Perl perlunitut Perl Unicode tutorial perlebcdic Considerations for running Perl on EBCDIC platforms @@ -144,8 +145,12 @@ For ease of access, the Perl manual has been split up into several sections. perlapio Perl internal IO abstraction interface perlhack Perl hackers guide + perlsource Guide to the Perl source tree + perlinterp Overview of the Perl intepreter source and how it works + perlhacktut Walk through the creation of a simple C code patch + perlhacktips Tips for Perl core C code hacking perlpolicy Perl development policies - perlrepository Perl source repository + perlgit Using git with the Perl repository =head2 Miscellaneous @@ -157,6 +162,21 @@ For ease of access, the Perl manual has been split up into several sections. perlhist Perl history records perldelta Perl changes since previous version + perl5141delta Perl changes in version 5.14.1 + perl5140delta Perl changes in version 5.14.0 + perl51311delta Perl changes in version 5.13.11 + perl51310delta Perl changes in version 5.13.10 + perl5139delta Perl changes in version 5.13.9 + perl5138delta Perl changes in version 5.13.8 + perl5137delta Perl changes in version 5.13.7 + perl5136delta Perl changes in version 5.13.6 + perl5135delta Perl changes in version 5.13.5 + perl5134delta Perl changes in version 5.13.4 + perl5133delta Perl changes in version 5.13.3 + perl5132delta Perl changes in version 5.13.2 + perl5131delta Perl changes in version 5.13.1 + perl5130delta Perl changes in version 5.13.0 + perl5123delta Perl changes in version 5.12.3 perl5122delta Perl changes in version 5.12.2 perl5121delta Perl changes in version 5.12.1 perl5120delta Perl changes in version 5.12.0 @@ -207,7 +227,6 @@ For ease of access, the Perl manual has been split up into several sections. perlaix Perl notes for AIX perlamiga Perl notes for AmigaOS - perlapollo Perl notes for Apollo DomainOS perlbeos Perl notes for BeOS perlbs2000 Perl notes for POSIX-BC BS2000 perlce Perl notes for WinCE @@ -254,12 +273,15 @@ often point out exactly where the trouble is. Perl officially stands for Practical Extraction and Report Language, except when it doesn't. -Perl is a language optimized for scanning arbitrary +Perl was originally a language optimized for scanning arbitrary text files, extracting information from those text files, and printing -reports based on that information. It's also a good language for many -system management tasks. The language is intended to be practical -(easy to use, efficient, complete) rather than beautiful (tiny, -elegant, minimal). +reports based on that information. It quickly became a good language +for many system management tasks. Over the years, Perl has grown into +a general-purpose programming language. It's widely used for everything +from quick "one-liners" to full-scale application development. + +The language is intended to be practical (easy to use, efficient, +complete) rather than beautiful (tiny, elegant, minimal). Perl combines (in the author's opinion, anyway) some of the best features of C, B<sed>, B<awk>, and B<sh>, so people familiar with @@ -273,16 +295,8 @@ unlimited depth. And the tables used by hashes (sometimes called "associative arrays") grow as necessary to prevent degraded performance. Perl can use sophisticated pattern matching techniques to scan large amounts of data quickly. Although optimized for -scanning text, Perl can also deal with binary data, and can make dbm -files look like hashes. Setuid Perl scripts are safer than C programs -through a dataflow tracing mechanism that prevents many stupid -security holes. - -If you have a problem that would ordinarily use B<sed> or B<awk> or -B<sh>, but it exceeds their capabilities or must run a little faster, -and you don't want to write the silly thing in C, then Perl may be for -you. There are also translators to turn your B<sed> and B<awk> -scripts into Perl scripts. +scanning text, Perl also has many excellent tools for slicing +and dicing binary data. But wait, there's more... @@ -396,9 +410,6 @@ Perl developers, please write to perl-thanks@perl.org . =head1 SEE ALSO - a2p awk to perl translator - s2p sed to perl translator - http://www.perl.org/ the Perl homepage http://www.perl.com/ Perl articles (O'Reilly) http://www.cpan.org/ the Comprehensive Perl Archive @@ -446,7 +457,7 @@ affected by wraparound). You may mail your bug reports (be sure to include full configuration information as output by the myconfig program in the perl source tree, or by C<perl -V>) to perlbug@perl.org . If you've succeeded -in compiling perl, the B<perlbug> script in the F<utils/> subdirectory +in compiling perl, the L<perlbug> script in the F<utils/> subdirectory can be used to help mail in a bug report. Perl actually stands for Pathologically Eclectic Rubbish Lister, but diff --git a/Master/tlpkg/tlperl/lib/pods/perl5110delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5110delta.pod index 1b722ed7e8e..7ceb174a09c 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl5110delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl5110delta.pod @@ -32,7 +32,7 @@ to match whichever property they like, including the new artificial definitions. B<NOTE:> This is a backwards incompatible no-warning change in behaviour. If you are upgrading and you process large volumes of text look for POSIX and Perl style character classes and -change them to the relevent property name (by removing the word 'Posix' from the current name). +change them to the relevant property name (by removing the word 'Posix' from the current name). The following table maps the POSIX character class names, the escapes and the old and new Unicode property mappings: @@ -63,7 +63,7 @@ in regcomp.h, and then setting PERL_TEST_LEGACY_POSIX_CC -to true your enviornment when testing. +to true your environment when testing. =head2 @INC reorganization @@ -1544,7 +1544,7 @@ simpler to spot and correct the suspicious character. =item * -Explicitely point to $. when it causes an uninitialized warning for ranges in scalar context +Explicitly point to $. when it causes an uninitialized warning for ranges in scalar context =item * diff --git a/Master/tlpkg/tlperl/lib/pods/perl5120delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5120delta.pod index 5d5b401e784..08c4285ebe9 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl5120delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl5120delta.pod @@ -199,9 +199,9 @@ See the documentation for C<ExtUtils::MakeMaker> or C<Module::Build> for more on how to specify C<configure_requires> when creating a distribution for CPAN. -=head2 C<each> is now more flexible +=head2 C<each>, C<keys>, C<values> are now more flexible -The C<each> function can now operate on arrays. +The C<each>, C<keys>, C<values> function can now operate on arrays. =head2 C<when> as a statement modifier @@ -287,7 +287,7 @@ those installed in C<ARCHLIB> and C<PRIVLIB>. =head2 REGEXPs are now first class -Internally, Perl now treates compiled regular expressions (such as +Internally, Perl now treats compiled regular expressions (such as those created with C<qr//>) as first class entities. Perl modules which serialize, deserialize or otherwise have deep interaction with Perl's internal data structures need to be updated for this change. Most @@ -497,7 +497,8 @@ longer be used as an attribute. =item * Perl's command-line switch "-P", which was deprecated in version 5.10.0, has -now been removed. +now been removed. The CPAN module C<< Filter::cpp >> can be used as an +alternative. =back @@ -588,7 +589,7 @@ on CPAN which require these should add them to their prerequisites. The core versions of these modules warnings will issue a deprecation warning. If you ship a packaged version of Perl, either alone or as part of a -larger system, then you should carefully consider the reprecussions of +larger system, then you should carefully consider the repercussions of core module deprecations. You may want to consider shipping your default build of Perl with packages for some or all deprecated modules which install into C<vendor> or C<site> perl library directories. This will @@ -1514,7 +1515,7 @@ The documentation for C<$1> in perlvar.pod has been clarified. =item * -C<\N{U+I<wide hex char>}> is now documented. +C<\N{U+I<code point>}> is now documented. =back @@ -1665,8 +1666,8 @@ C<\N{...}> now compiles better, always forces UTF-8 internal representation Perl's developers have fixed several problems with the recognition of C<\N{...}> constructs. As part of this, perl will store any scalar -or regex containing C<\N{I<name>}> or C<\N{U+I<wide hex char>}> in its -definition in UTF-8 format. (This was true previously for all occurences +or regex containing C<\N{I<name>}> or C<\N{U+I<code point>}> in its +definition in UTF-8 format. (This was true previously for all occurrences of C<\N{I<name>}> that did not use a custom translator, but now it's always true.) diff --git a/Master/tlpkg/tlperl/lib/pods/perl5121delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5121delta.pod index 2c8a08fb289..cc2702bcc32 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl5121delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl5121delta.pod @@ -2,7 +2,7 @@ =head1 NAME -perldelta - what is new for perl v5.12.1 +perl5121delta - what is new for perl v5.12.1 =head1 DESCRIPTION @@ -60,7 +60,7 @@ We made a small fix to the L<CPANPLUS> test suite to fix an occasional spurious =item * -We upgraded L<Safe> to version 2.27 to wrap coderefs retured by C<reval()> and C<rdo()>. +We upgraded L<Safe> to version 2.27 to wrap coderefs returned by C<reval()> and C<rdo()>. =back @@ -257,7 +257,7 @@ See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=74290> =item * We fixed a regression in case-insensitive matching of folded characters -in regular expressions introduced in Perl 5.12.0. +in regular expressions introduced in Perl 5.10.1. See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=72998> diff --git a/Master/tlpkg/tlperl/lib/pods/perl5122delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5122delta.pod index 9a150cc0100..445e74dea77 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl5122delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl5122delta.pod @@ -58,8 +58,8 @@ overriding C<caller()> incorrectly. =item C<CPANPLUS> A patch to F<cpanp-run-perl> has been backported from CPANPLUS C<0.9004>. This -resolves L<[perl #55964]|http://rt.perl.org/rt3/Ticket/Display.html?id=55964> -and L<[perl #57106]|http://rt.perl.org/rt3/Ticket/Display.html?id=57106>, both +resolves L<RT #55964|http://rt.cpan.org/Public/Bug/Display.html?id=55964> +and L<RT #57106|http://rt.cpan.org/Public/Bug/Display.html?id=57106>, both of which related to failures to install distributions that use C<Module::Install::DSL>. @@ -89,12 +89,12 @@ name is empty; C<abs2rel()> properly handles Unix-style input. =over -=item * +=item * F<perlbug> now always gives the reporter a chance to change the email address it guesses for them. -=item * +=item * F<perlbug> should no longer warn about uninitialized values when using the C<-d> and C<-v> options. @@ -226,7 +226,7 @@ now supports get/set magic and thus tied buffers correctly. =item * -The C<pp_getc>, C<pp_tell>, and C<pp_eof> opcodes now make room on the +The C<pp_getc>, C<pp_tell>, and C<pp_eof> opcodes now make room on the stack for their return values in cases where no argument was passed in. =item * @@ -241,7 +241,7 @@ See L<[perl #75680]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75680> =head2 AIX -=over +=over =item * @@ -258,7 +258,7 @@ suite. When building Perl with the mingw64 x64 cross-compiler C<incpath>, C<libpth>, C<ldflags>, C<lddlflags> and C<ldflags_nolargefiles> values -in F<Config.pm> and F<Config_heavy.pl> were not previously not being set +in F<Config.pm> and F<Config_heavy.pl> were not previously being set correctly because, with that compiler, the include and lib directories are not immediately below C<$(CCHOME)>. diff --git a/Master/tlpkg/tlperl/lib/pods/perl5123delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5123delta.pod index 20d38bb15ca..35da9af23ca 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl5123delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl5123delta.pod @@ -2,7 +2,7 @@ =head1 NAME -perldelta - what is new for perl v5.12.3 +perl5123delta - what is new for perl v5.12.3 =head1 DESCRIPTION @@ -34,7 +34,8 @@ constant expressions. Module::Build should be more reliably pass its tests under cygwin. -lvalue sub return values are now COW. +Lvalue subroutines are again able to return copy-on-write scalars. This +had been broken since version 5.10.0. =head1 Platform Specific Notes diff --git a/Master/tlpkg/tlperl/lib/pods/perl5130delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5130delta.pod new file mode 100644 index 00000000000..c5d5169b54e --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5130delta.pod @@ -0,0 +1,133 @@ +=encoding utf8 + +=head1 NAME + +perl5130delta - what is new for perl v5.13.0 + +=head1 DESCRIPTION + +This document describes differences between the 5.12.0 release and the +5.13.0 release. + +If you are upgrading from an earlier release such as 5.10.0, first read +L<perl5120delta>, which describes differences between 5.10.0 and +5.12.0. + +=head1 Core Enhancements + +=head2 "safe signals" optimization + +Signal dispatch has been moved from the runloop into control ops. This +should give a few percent speed increase, and eliminates almost all of +the speed penalty caused by the introduction of "safe signals" in +5.8.0. Signals should still be dispatched within the same statement as +they were previously - if this is not the case, or it is possible to +create uninterruptible loops, this is a bug, and reports are encouraged +of how to recreate such issues. + +=head2 Assignment to C<$0> sets the legacy process name with C<prctl()> on Linux + +On Linux the legacy process name will be set with L<prctl(2)>, in +addition to altering the POSIX name via C<argv[0]> as perl has done +since version 4.000. Now system utilities that read the legacy process +name such as ps, top and killall will recognize the name you set when +assigning to C<$0>. The string you supply will be cut off at 16 bytes, +this is a limitation imposed by Linux. + +=head2 Optimization of shift; and pop; calls without arguments + +Additional two OPs are not added anymore into op tree for shift and pop +calls without argument (when it works on C<@_>). Makes C<shift;> 5% +faster over C<shift @_;> on not threaded perl and 25% faster on threaded. + +=head1 Modules and Pragmata + +=head2 Updated Modules + +=over 4 + +=item CGI + +Updated to version 3.49. + +=item Data::Dumper + +Updated to version 2.126. + +=item MIME::Base64 + +Updated to 3.09. + +=item threads + +Updated to version 1.77 + +=item threads-shared + +Updated to version 1.33 + +=back + +=head1 Installation and Configuration Improvements + +=head2 Platform Specific Changes + +=over 4 + +=item AIX + +Allow building on AIX 4.2. + +=back + +=head1 Acknowledgements + +Perl 5.13.0 represents eight days of development since Perl 5.12.0 and +contains 3,766 lines of changes across 151 files from 29 authors and +committers. + +Thank you to the following for contributing to this release: + +Ævar Arnfjörð Bjarmason, Alex Vandiver, Chris Williams, chromatic, +Craig A. Berry, David Golden, David Mitchell, Eric Brine, Father +Chrysostomos, Florian Ragwitz, Frank Wiegand, Gisle Aas, H.Merijn +Brand, Hugo van der Sanden, Jesse Vincent, Josh ben Jore, Karl +Williamson, Leon Brocard, Michael G Schwern, Michael G. Schwern, Nga +Tang Chan, Nicholas Clark, Niko Tyni, Rafael Garcia-Suarez, Ricardo +Signes, Robin Barker, Slaven Rezic, Steffen Mueller, Zefram. + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl bug +database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> +program included with your release. Be sure to trim your bug down to a +tiny but sufficient test case. Your bug report, along with the output +of C<perl -V>, will be sent off to perlbug@perl.org to be analysed by +the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please +send it to perl5-security-report@perl.org. This points to a closed +subscription unarchived mailing list, which includes all the core +committers, who be able to help assess the impact of issues, figure out +a resolution, and help co-ordinate the release of patches to mitigate +or fix the problem across all platforms on which Perl is supported. +Please only use this address for security issues in the Perl core, not +for modules independently distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive +details on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl51310delta.pod b/Master/tlpkg/tlperl/lib/pods/perl51310delta.pod new file mode 100644 index 00000000000..846e2253f30 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl51310delta.pod @@ -0,0 +1,814 @@ +=encoding utf8 + +=head1 NAME + +perl51310delta - what is new for perl v5.13.10 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.9 release and +the 5.13.10 release. + +If you are upgrading from an earlier release such as 5.13.8, first read +L<perl5139delta>, which describes differences between 5.13.8 and +5.13.9. + +=head1 Core Enhancements + +=head2 The new regular expression modifiers available in suffix form + +Various releases of the 5.13.x series have added new regular expression +modifiers, C</a>, C</d>, C</l>, and C</u>. They were only available in +infix form (e.g., C<(?a:...)>) until this release; now they are usable +in suffix form. This change was made too late to change all the +affected documentation, so there are a number of places that erroneously +say these must be used in infix form. + +However, there is an ambiguity with the construct, C<s/foo/bar/le...>. Due +to backward compatibility constraints, in Perl 5.14 only, it will be +resolved as C<s/foo/bar/ le...>, that is, as meaning to take the result +of the substitution, and see if it is stringwise less-than-or-equal-to +what follows. In Perl 5.16 and later, it will instead be resolved as +meaning to do the pattern match using the rules of the current locale, +and evaluate the rhs as an expression when doing the substitution. In +5.14, if you want the latter interpretation, you can write "el" instead. + +=head2 Add C<\p{Titlecase}> as a synonym for C<\p{Title}> + +This synonym is added for symmetry with the Unicode property names +C<\p{Uppercase}> and C<\p{Lowercase}>. + +=head2 New regular expression modifier option C</aa> + +Doubling the C</a> regular expression modifier increases its effect, +so that in case-insensitive matching, no ASCII character will match a +non-ASCII character. For example, normally, + + 'k' =~ /\N{KELVIN SIGN}/i + +will match; it won't under C</aa>. + +=head2 New warnings categories for problematic (non-)Unicode code points. + +Three new warnings subcategories of <utf8> have been added. These +allow you to turn off warnings for their covered events, while allowing +the other UTF-8 warnings to remain on. The three categories are: +C<surrogate> when UTF-16 surrogates are encountered; +C<nonchar> when Unicode non-character code points are encountered; +and C<non_unicode> when code points that are above the legal Unicode +maximum of 0x10FFFF are encountered. + +=head1 Incompatible Changes + +=head2 Most C<\p{}> properties are now immune from case-insensitive matching + +For most Unicode properties, it doesn't make sense to have them match +differently under C</i> case-insensitive matching than not. And doing +so leads to unexpected results and potential security holes. For +example + + m/\p{ASCII_Hex_Digit}+/i + +could previously match non-ASCII characters because of the Unicode +matching rules. There were a number of bugs in this feature until an +earlier release in the 5.13 series. Now this release reverts, and +removes the feature completely except for the few properties where +people have come to expect it, namely the ones where casing is an +integral part of their functionality, such as C<m/\p{Uppercase}/i> and +C<m/\p{Lowercase}/i>, both of which match the exact same code points, +namely those matched by C<m/\p{Cased}/i>. Details are in +L<perlrecharclass/Unicode Properties>. + +User-defined property handlers that need to match differently under +C</i> must change to read the new boolean parameter passed it which is +non-zero if case-insensitive matching is in effect; 0 if not. See +L<perluniprops/User-Defined Character Properties>. + +=head2 regex: \p{} in pattern implies Unicode semantics + +Now, a Unicode property match specified in the pattern will indicate +that the pattern is meant for matching according to Unicode rules +(e40e74f) + +=head2 add GvCV_set() and GvGP_set() macros and change GvGP() + +This allows a future commit to eliminate some backref magic between GV +and CVs, which will require complete control over assignment to the +gp_cv slot. + +If you've been using GvGP() in lvalue context this change will break +your code, you should use GvGP_set() instead. (c43ae56) + +=head2 _swash_inversion_hash is no longer exported as part of the API + +This function shouldn't be called from XS code. (4c2e113) + +=head2 Unreferenced objects in global destruction + +The fix for [perl #36347], which made sure that destructors were called on +unreferenced objects, broke the tests for three CPAN modules, which +apparently rely on the bug. + +To provide more time for fixing them (as this is such a minor bug), we +have reverted the fix until after perl 5.14.0. + +This resolves [perl #82542] and other related tickets. + +=head2 C<close> on shared pipes + +The C<close> function no longer waits for the child process to exit if the +underlying file descriptor is still in use by another thread, to avoid +deadlocks. It returns true in such cases. + +=head1 Deprecations + +=over + +=item Deprecated Modules + +The following modules will be removed from the core distribution in a +future release, and should be installed from CPAN instead. Distributions +on CPAN which require these should add them to their prerequisites. The +core versions of these modules warnings will issue a deprecation warning. + +If you ship a packaged version of Perl, either alone or as part of a +larger system, then you should carefully consider the repercussions of +core module deprecations. You may want to consider shipping your default +build of Perl with packages for some or all deprecated modules which +install into C<vendor> or C<site> perl library directories. This will +inhibit the deprecation warnings. + +Alternatively, you may want to consider patching F<lib/deprecate.pm> +to provide deprecation warnings specific to your packaging system +or distribution of Perl, consistent with how your packaging system +or distribution manages a staged transition from a release where the +installation of a single package provides the given functionality, to +a later release where the system administrator needs to know to install +multiple packages to get that same functionality. + +You can silence these deprecation warnings by installing the modules +in question from CPAN. To install the latest version of all of them, +just install C<Task::Deprecations::5_14>. + +=over + +=item L<Devel::DProf> + +We strongly recommend that you install and used L<Devel::NYTProf> in +preference, as it offers significantly improved profiling and reporting. + +=back + +=back + +=head2 User-defined case-mapping + +This feature is being deprecated due to its many issues, as documented in +L<perlunicode/User-Defined Case Mappings (for serious hackers only)>. +It is planned to remove this feature in Perl 5.16. A CPAN module +providing improved functionality is being prepared for release by the +time 5.14 is. + +=head1 Modules and Pragmata + +=head2 New Modules and Pragmata + +=over 4 + +=item * + +C<CPAN::Meta> version 2.110440 has been added as a dual-life module. It +provides a standard library to read, interpret and write CPAN distribution +metadata files (e.g. META.json and META.yml) which describes a +distribution, its contents, and the requirements for building it and +installing it. The latest CPAN distribution metadata specification is +included as C<CPAN::Meta::Spec> and notes on changes in the specification +over time are given in C<CPAN::Meta::History>. + +=item * + +C<Version::Requirements> version 0.101020 has been added as a dual-life +module. It provides a standard library to model and manipulates module +prerequisites and version constraints as defined in the L<CPAN::Meta::Spec>. + +=back + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +C<B> has been upgraded from version 1.27 to 1.28. + +=item * + +C<Carp> has been upgraded from version 1.19 to 1.20. + +[perl #82854] It now avoids using regular expressions that cause perl to +load its Unicode tables, in order to avoid the 'BEGIN not safe after +errors' error that will ensue if there has been a syntax error. + +=item * + +C<CGI> has been upgraded from version 3.51 to 3.52 + +=item * + +C<CPAN> has been upgraded from version 1.94_64 to 1.94_65 + +Includes support for META.json and MYMETA.json. + +=item * + +C<CPANPLUS> has been upgraded from version 0.9011 to 0.9101 + +Includes support for META.json and MYMETA.json and a change to +using Digest::SHA for CPAN checksums. + +=item * + +C<deprecate> has been upgraded from version 0.01 to 0.02. + +=item * + +C<diagnostics> has been upgraded from version 1.21 to 1.22. + +It now renders pod links slightly better, and has been taught to find +descriptions for messages that share their descriptions with other +messages. + +=item * + +C<Devel::DProf> has been upgraded from version 20080331.00 to 20110217.00. + +Merely loading C<Devel::DProf> now no longer triggers profiling to start. +C<use Devel::DProf> and C<perl -d:DProf ...> still behave as before and start +the profiler. + +NOTE: C<Devel::DProf> is deprecated and will be removed from a future +version of Perl. We strongly recommend that you install and use +L<Devel::NYTProf> instead, as it offers significantly improved +profiling and reporting. + +=item * + +C<DynaLoader> has been upgraded from version 1.12 to 1.13. + +[perl #84358] It no longer inherits from AutoLoader; hence it no longer +produces weird error messages for unsuccessful method calls on classes that +inherit from DynaLoader. + +=item * + +C<IO::Select> has been upgraded from version 1.17 to 1.18. + +It now allows IO::Handle objects (and objects in derived classes) to be +removed from an IO::Select set even if the underlying file descriptor is +closed or invalid. + +=item * + +C<IPC::Cmd> has been upgraded from version 0.68 to 0.70 + +=item * + +C<HTTP::Tiny> has been upgraded from version 0.009 to 0.010 + +=item * + +C<Math::BigInt> has been upgraded from version 1.99_04 to 1.992. + +=item * + +C<Module::Build> has been upgraded from version 0.3607 to 0.37_05. + +A notable change is the deprecation of several modules. +Module::Build::Version has been deprecated and Module::Build now relies +directly upon L<version>. Module::Build::ModuleInfo has been deprecated in +favor of a standalone copy of it called L<Module::Metadata>. +Module::Build::YAML has been deprecated in favor of L<CPAN::Meta::YAML>. + +Module::Build now also generates META.json and MYMETA.json files +in accordance with version 2 of the CPAN distribution metadata specification, +L<CPAN::Meta::Spec>. The older format META.yml and MYMETA.yml files are +still generated, as well. + +=item * + +C<Module::Load::Conditional> has been upgraded from version 0.40 to 0.44 + +=item * + +C<Module::Metadata> has been upgraded from version 1.000003 to 1.000004. + +=item * + +C<overload> has been upgraded from version 1.12 to 1.13. + +The documentation has greatly improved. See L</Documentation> below. + +=item * + +C<Parse::CPAN::Meta> has been upgraded from version 1.40 to 1.4401. + +The latest Parse::CPAN::Meta can now read YAML or JSON files using +L<CPAN::Meta::YAML> and L<JSON::PP>, which are now part of the Perl core. + +=item * + +C<re> has been upgraded from version 0.16 to 0.17. + +It now supports the double-a flag: C<use re '/aa';> + +The C<regmust> function used to crash when called on a regular expression +belonging to a pluggable engine. Now it has been disabled for those. + +C<regmust> no longer leaks memory. + +=item * + +C<Term::UI> has been upgraded from version 0.24 to 0.26 + +=item * + +C<Unicode::Collate> has been upgraded from version 0.68 to 0.72 + +This also sees the switch from using the pure-perl version of this +module to the XS version.` + +=item * + +C<VMS::DCLsym> has been upgraded from version 1.04 to 1.05. + +Two bugs have been fixed [perl #84086]: + +The symbol table name was lost when tying a hash, due to a thinko in +C<TIEHASH>. The result was that all tied hashes interacted with the +local symbol table. + +Unless a symbol table name had been explicitly specified in the call +to the constructor, querying the special key ':LOCAL' failed to +identify objects connected to the local symbol table. + +=item * + +Added new function C<Unicode::UCD::num()>. This function will return the +numeric value of the string passed it; C<undef> if the string in its +entirety has no safe numeric value. + +To be safe, a string must be a single character which has a numeric +value, or consist entirely of characters that match \d, coming from the +same Unicode block of digits. Thus, a mix of Bengali and Western +digits would be considered unsafe, as well as a mix of half- and +full-width digits, but strings consisting entirely of Devanagari digits +or of "Mathematical Bold" digits would would be safe. + +=item * + +C<CPAN> has been upgraded from version 1.94_63 to 1.94_64. + +=back + +=head1 Documentation + +=head2 Changes to Existing Documentation + +=head3 L<overload> + +=over 4 + +=item * + +L<overload>'s documentation has practically undergone a rewrite. It +is now much more straightforward and clear. + +=back + +=head3 L<perlhack> and perlrepository + +=over 4 + +=item * + +The L<perlhack> and perlrepository documents have been heavily edited and +split up into several new documents. + +The L<perlhack> document is now much shorter, and focuses on the Perl 5 +development process and submitting patches to Perl. The technical content has +been moved to several new documents, L<perlsource>, L<perlinterp>, +L<perlhacktut>, and L<perlhacktips>. This technical content has only been +lightly edited. + +The perlrepository document has been renamed to L<perlgit>. This new document +is just a how-to on using git with the Perl source code. Any other content +that used to be in perlrepository has been moved to perlhack. + +=back + +=head3 L<perlfunc> + +=over 4 + +=item * + +The documentation for the C<map> function now contains more examples, +see B<perldoc -f map> (f947627) + +=back + +=head3 L<perlfaq4> + +=over 4 + +=item * + +Examples in L<perlfaq4> have been updated to show the use of +L<Time::Piece>. (9243591) + +=back + +=head3 Miscellaneous + +=over 4 + +=item * + +Many POD related RT bugs and other issues which are too numerous to +enumerate have been solved by Michael Stevens. + +=back + +=head1 Diagnostics + +The following additions or changes have been made to diagnostic output, +including warnings and fatal error messages. For the complete list of +diagnostic messages, see L<perldiag>. + +=head2 New Diagnostics + +=over 4 + +=item "\b{" is deprecated; use "\b\{" instead + +=item "\B{" is deprecated; use "\B\{" instead + +Use of an unescaped "{" immediately following a C<\b> or C<\B> is now +deprecated so as to reserve its use for Perl itself in a future release. + +=item regcomp: Add warning if \p is used under locale. (fb2e24c) + +C<\p> implies Unicode matching rules, which are likely going to be +different than the locale's. + +=item panic: gp_free failed to free glob pointer - something is repeatedly re-creating entries + +This new error is triggered if a destructor called on an object in a +typeglob that is being freed creates a new typeglob entry containing an +object with a destructor that creates a new entry containing an object.... + +=item refcnt: fd %d%s + +This new error only occurs if a internal consistency check fails when a +pipe is about to be closed. + +=back + +=head2 Changes to Existing Diagnostics + +=over 4 + +=item * + +The warning message about regex unrecognized escapes passed through is +changed to include any literal '{' following the 2-char escape. e.g., +"\q{" will include the { in the message as part of the escape +(216bfc0). + +=item * + +C<binmode $fh, ':scalar'> no longer warns (8250589) + +Perl will now no longer produce this warning: + + $ perl -we 'open my $f, ">", \my $x; binmode $f, "scalar"' + Use of uninitialized value in binmode at -e line 1. + +=back + +=head1 Utility Changes + +=head3 L<perlbug> + +=over 4 + +=item * + +[perl #82996] Use the user's from address as return-path in perlbug + +Many systems these days don't have a valid Internet domain name and +perlbug@perl.org does not accept email with a return-path that does +not resolve. Therefore pass the user's address to sendmail so it's +less likely to get stuck in a mail queue somewhere. (019cfd2) + +=back + +=head1 Configuration and Compilation + +=over 4 + +=item * + +make reg_eval_scope.t TODOs consistently fail (daaf7ac) + +Some of the TODO tests in reg_eval_scope.t spuriously passed under +non-threaded builds. Make the tests harder so they always fail. + +Since one of the key bugs in (?{..}) is the trashing of the parent pad, +add some extra lexical vars to the parent scope and check they're still +there at the end. + +=item * + +Stop EU::CBuilder's tests from failing in parallel (cbf59d5) + +It used to use the same paths for temporary files in all tests. This +blew up randomly when the tests were run in parallel. + +=back + +=head1 Testing + +=over 4 + +=item * + +F<porting/FindExt.t> now skips all tests on a static (-Uusedl) build +of perl. + +=item * + +F<porting/FindExt.t> now passes on non-Win32 platforms when some +extensions are built statically. + +=back + +=head1 Platform Support + +=head2 Platform-Specific Notes + +=over 4 + +=item Windows + +=over 4 + +=item * + +The C<test-prep> build target now depends on F<pod/perltoc.pod> to allow the +F<t/porting/buildtoc.t> test to run successfully. + +=back + +=item MirBSD + +=over 4 + +=item * + +[perl #82988] Skip hanging taint.t test on MirBSD 10 (1fb83d0) + +Skip a hanging test under MirBSD that was already being skipped under +OpenBSD. + +=item * + +Previously if you build perl with a shared libperl.so on MirBSD (the +default config), it will work up to the installation; however, once +installed, it will be unable to find libperl. Treat path handling +like in the other BSD dialects. + +=back + +=back + +=head1 Internal Changes + +=over 4 + +=item * + +Fix harmless invalid read in Perl_re_compile() (f6d9469) + +[perl #2460] described a case where electric fence reported an invalid +read. This could be reproduced under valgrind with blead and -e'/x/', +but only on a non-debugging build. + +This was because it was checking for certain pairs of nodes (e.g. BOL + END) +and wasn't allowing for EXACT nodes, which have the string at the next +node position when using a naive NEXTOPER(first). In the non-debugging +build, the nodes aren't initialised to zero, and a 1-char EXACT node isn't +long enough to spill into the type field of the "next node". + +Fix this by only using NEXTOPER(first) when we know the first node is +kosher. + +=item * + +Break out the generated function Perl_keywords() into F<keywords.c>, a new file. (26ea9e1) + +As it and Perl_yylex() both need FEATURE_IS_ENABLED, feature_is_enabled() is +no longer static, and the two macro definitions move from toke.c to perl.h + +Previously, one had to cut and paste the output of perl_keywords.pl into the +middle of toke.c, and it was not clear that it was generated code. + +=item * + +A lot of tests have been ported from Test to Test::More, e.g. in +3842ad6. + +=item * + +Increase default PerlIO buffer size. (b83080d) + +The previous default size of a PerlIO buffer (4096 bytes) has been increased +to the larger of 8192 bytes and your local BUFSIZ. Benchmarks show that doubling +this decade-old default increases read and write performance in the neighborhood +of 25% to 50% when using the default layers of perlio on top of unix. To choose +a non-default size, such as to get back the old value or to obtain and even +larger value, configure with: + + ./Configure -Accflags=-DPERLIOBUF_DEFAULT_BUFSIZ=N + +where N is the desired size in bytes; it should probably be a multiple of +your page size. + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +A Unicode C<\p{}> property match in a regular expression pattern will +now force Unicode rules for the rest of the regular expression + +=item * + +[perl #38456] binmode FH, ":crlf" only modifies top crlf layer (7826b36) + +When pushed on top of the stack, crlf will no longer enable crlf layers +lower in the stack. This will prevent unexpected results. + +=item * + +Fix 'raw' layer for RT #80764 (ecfd064) + +Made a ':raw' open do what it advertises to do (first open the file, +then binmode it), instead of leaving off the top layer. + +=item * + +Use PerlIOBase_open for pop, utf8 and bytes layers (c0888ac) + +Three of Perl's builtin PerlIO layers (C<:pop>, C<:utf8> and +C<:bytes>) didn't allow stacking when opening a file. For example +this: + + open FH, '>:pop:perlio', 'some.file' or die $!; + +Would throw an error: "Invalid argument". This has been fixed in this +release. + +=item * + +An issue present since 5.13.1, where s/A/B/ with A utf8 and B +non-utf8, could cause corruption or segfaults has been +fixed. (c95ca9b) + +=item * + +String evals will no longer fail after 2 billion scopes have been +compiled (d1bfb64, 2df5bdd, 0d311cd and 6012dc8) + +=item * + +[perl #81750] When strict 'refs' mode is off, +C<%{...}> in rvalue context returns C<undef> if +its argument is undefined. An optimisation introduced in perl 5.12.0 to +make C<keys %{...}> faster when used as a boolean did not take this into +account, causing C<keys %{+undef}> (and C<keys %$foo> when C<$foo> is +undefined) to be an error, which it should only be in strict mode. + +=item * + +[perl #83194] Combining the vector (%v) flag and dynamic precision would +cause sprintf to confuse the order of its arguments, making it treat the +string as the precision and vice versa. + +=item * + +[perl #77692] Sometimes the UTF8 length cache would not be reset on a value +returned by substr, causing C<length(substr($uni_string,...))> to give +wrong answers. With C<${^UTF8CACHE}> set to -1, it would produce a 'panic' +error message, too. + +=item * + +During the restoration of a localised typeglob on scope exit, any +destructors called as a result would be able to see the typeglob in an +inconsistent state, containing freed entries, which could result in a +crash. This would affect code like this: + + local *@; + eval { die bless [] }; # puts an object in $@ + sub DESTROY { + local $@; # boom + } + +Now the glob entries are cleared before any destructors are called. This +also means that destructors can vivify entries in the glob. So perl tries +again and, if the entries are re-created too many times, dies with a +'panic: gp_free...' error message. + +=item * + +[perl #78494] When pipes are shared between threads, the C<close> function +(and any implicit close, such as on thread exit) no longer blocks. + +=item * + +Several contexts no longer allow a Unicode character to begin a word +that should never begin words, for an example an accent that must follow +another character previously could precede all other characters. + +=item * + +Case insensitive matching in regular expressions compiled under C<use +locale> now works much more sanely when the pattern and/or target string +are encoded in UTF-8. Previously, under these conditions the localeness +was completely lost. Now, code points above 255 are treated as Unicode, +but code points between 0 and 255 are treated using the current locale +rules, regardless of whether the pattern or string are encoded in UTF-8. +The few case insensitive matches that cross the 255/256 boundary are not +allowed. For example, 0xFF does not caselessly match the character at +0x178, LATIN CAPITAL LETTER Y WITH DIAERESIS, because 0xFF may not be +LATIN SMALL LETTER Y in the current locale, and Perl has no way of +knowing if that character even exists in the locale, much less what code +point it is. + +=back + +=head1 Acknowledgements + +Perl 5.13.10 represents approximately one month of development since +Perl 5.13.9 and contains approximately 63000 lines of changes across +609 files from 38 authors and committers: + +Abigail, Alexander Hartmaier, brian d foy, Charles Bailey, Chip +Salzenberg, Chris 'BinGOs' Williams, Craig A. Berry, Curtis Jewell, +Dave Rolsky, David Golden, David Leadbeater, David Mitchell, David +Wheeler, Father Chrysostomos, Florian Ragwitz, Franz Fasching, George +Greer, H.Merijn Brand, Hongwen Qiu, Hugo van der Sanden, Jay Hannah, +Jesse Vincent, Karl Williamson, Larwan Berke, Leon Timmermans, Michael +Breen, Michael Stevens, Nicholas Clark, Noirin Shirley, Paul Evans, +Peter John Acklam, Ricardo Signes, Robin Barker, Steven Schubiger, Tom +Christiansen, Tony Cook, Zsbán Ambrus and Ævar Arnfjörð Bjarmason + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the L<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl51311delta.pod b/Master/tlpkg/tlperl/lib/pods/perl51311delta.pod new file mode 100644 index 00000000000..8d537e9c8d8 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl51311delta.pod @@ -0,0 +1,513 @@ +=encoding utf8 + +=head1 NAME + +perl51311delta - what is new for perl v5.13.11 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.10 release and +the 5.13.11 release. + +If you are upgrading from an earlier release such as 5.13.9, first read +L<perl5139delta>, which describes differences between 5.13.9 and +5.13.10. + +=head1 Security + +=head2 User-defined regular expression properties + +Perl no longer allows a tainted regular expression to invoke a user-defined +property via C<\p{...}> syntax. It simply dies instead [perl #82616]. + +=head1 Incompatible Changes + +=head2 local($_) will strip all magic from $_ + +local() on scalar variables will give them a new value, but keep all +their magic intact. This has proven to be problematic for the default +scalar variable $_, where L<perlsub> recommends that any subroutine +that assigns to $_ should localize it first. This would throw an +exception if $_ is aliased to a read-only variable, and could have +various unintentional side-effects in general. + +Therefore, as an exception to the general rule, local($_) will not +only assign a new value to $_, but also remove all existing magic from +it as well. + +=head2 Passing references to warn() + +An earlier Perl 5.13.x release changed C<warn($ref)> to leave the reference +unchanged, allowing C<$SIG{__WARN__}> handlers to access the original +reference. But this stopped warnings that were references from having the +file and line number appended even when there was no C<$SIG{__WARN__}> +handler in place. + +Now C<warn> checks for the presence of such a handler and, if there is +none, proceeds to stringify the reference and append the file and line +number. This allows simple uses of C<warn> for debugging to continue to +work as they did before. + +=head2 fork() emulation will not wait for signalled children + +On Windows parent processes would not terminate until all forked +childred had terminated first. However, C<kill('KILL', ...)> is +inherently unstable on pseudo-processes, and C<kill('TERM', ...)> +might not get delivered if the child if blocked in a system call. + +To avoid the deadlock and still provide a safe mechanism to terminate +the hosting process, Perl will now no longer wait for children that +have been sent a SIGTERM signal. It is up to the parent process to +waitpid() for these children if child clean-up processing must be +allowed to finish. However, it is also the responsibility of the +parent then to avoid the deadlock by making sure the child process +can't be blocked on I/O either. + +See L<perlfork> for more information about the fork() emulation on +Windows. + +=head2 Perl source code is read in text mode on Windows + +Perl scripts used to be read in binary mode on Windows for the benefit +of the ByteLoader module (which is no longer part of core Perl). This +had the side effect of breaking various operations on the DATA filehandle, +including seek()/tell(), and even simply reading from DATA after file handles +have been flushed by a call to system(), backticks, fork() etc. + +The default build options for Windows have been changed to read Perl source +code on Windows in text mode now. Hopefully ByteLoader will be updated on +CPAN to automatically handle this situation. + +=head1 Performance Enhancements + +=over 4 + +=item * + +An earlier optimisation to speed up C<my @array = ...> and +C<my %hash = ...> assignments caused a bug and was disabled in Perl 5.12.0. + +Now we have found another way to speed up these assignments [perl #82110]. + +=back + +=head1 Modules and Pragmata + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +C<attributes> has been upgraded from version 0.13 to 0.14. + +=item * + +C<base> has been upgraded from version 2.15 to 2.16. + +=item * + +C<CPAN> has been upgraded from version 1.94_65 to 1.9600. + +=item * + +C<CPANPLUS> has been upgraded from version 0.9101 to 0.9103 + +=item * + +C<CPANPLUS::Dist::Build> has been upgraded from version 0.52 to 0.54 + +=item * + +C<Cwd> has been downgraded from version 3.37 to 3.36. + +An optimisation that recent core changes have rendered unnecessary has been +reverted. + +=item * + +C<Devel::DProf> has been upgraded from version 20110225.01 to 20110228.00. + +=item * + +C<Digest::SHA> has been upgraded from version 5.50 to 5.61 + +New SHA-512/224 and SHA-512/256 transforms ref. NIST Draft FIPS 180-4 (February 2011) + +=item * + +C<ExtUtils::Command> has been upgraded from version 1.16 to 1.17. + +=item * + +C<File::Copy> has been downgraded from version 2.22 to 2.21. + +An optimisation that recent core changes have rendered unnecessary has been +reverted. + +=item * + +C<File::Glob> has been upgraded from version 1.11 to 1.12. + +=item * + +C<GDBM_File> has been upgraded from version 1.13 to 1.14. + +=item * + +C<Hash::Util> has been upgraded from version 0.10 to 0.11. + +=item * + +C<Hash::Util::FieldHash> has been upgraded from version 1.08 to 1.09. + +=item * + +C<HTTP::Tiny> has been upgraded from version 0.010 to 0.011. + +=item * + +C<I18N::Langinfo> has been upgraded from version 0.07 to 0.08. + +=item * + +C<IO> has been upgraded from version 1.25_03 to 1.25_04. + +=item * + +C<JSON::PP> has been upgraded from version 2.27103 to 2.27105 + +=item * + +C<Locale::Codes> has been upgraded from version 3.15 to 3.16 + +=item * + +C<Math::BigInt> has been upgraded from version 1.992 to 1.994 + +=item * + +C<Math::BigInt::FastCalc> has been upgraded from version 0.24_02 to 0.28 + +=item * + +C<Module::Build> has been upgraded from version 0.37_05 to 0.3800 + +=item * + +C<Module::CoreList> has been upgraded from version 2.45 to 2.46. + +=item * + +C<mro> has been upgraded from version 1.06 to 1.07. + +=item * + +C<NDBM_File> has been upgraded from version 1.11 to 1.12. + +=item * + +C<parent> has been upgraded from version 0.224 to 0.225 + +=item * + +C<Pod::Simple> has been upgraded from version 3.15 to 3.16 + +=item * + +C<Storable> has been upgraded from version 2.26 to 2.27. + +=item * + +C<Sys::Hostname> has been upgraded from version 1.15 to 1.16. + +=item * + +C<Test::Harness> has been upgraded from version 3.22 to 3.23 + +=item * + +C<Test::Simple> has been upgraded from version 0.97_01 to 0.98 + +=item * + +C<Tie::Hash::NamedCapture> has been upgraded from version 0.07 to 0.08. + +Some of the Perl code has been converted to XS for efficency's sake. + +=item * + +C<Tie::RefHash> has been upgraded from version 1.38 to 1.39. + +=item * + +C<Unicode::Collate> has been upgraded from version 0.72 to 0.73 + +DUCET has been updated for Unicode 6.0.0 as Collate/allkeys.txt and +the default UCA_Version is 22. + +=item * + +C<Unicode::UCD> has been upgraded from version 0.31 to 0.32. +This includes a number of bug fixes: + +=over 4 + +=item charinfo() + +=over 4 + +=item * + +It is now updated to Unicode Version 6 with Corrigendum #8, except, +as with Perl 5.14, the code point at U+1F514 has no name. + +=item * + +The Hangul syllable code points have the correct names, and their +decompositions are always output without requiring L<Lingua::KO::Hangul::Util> +to be installed. + +=item * + +The CJK (Chinese-Japanese-Korean) code points U+2A700 - U+2B734 +and U+2B740 - 2B81D are now properly handled. + +=item * + +The numeric values are now output for those CJK code points that have them. + +=item * + +The names that are output for code points with multiple aliases are now the +corrected ones. + +=back + +=item charscript() + +This now correctly returns "Unknown" instead of C<undef> for the script +of a code point that hasn't been assigned another one. + +=item charblock() + +This now correctly returns "No_Block" instead of C<undef> for the block +of a code point that hasn't been assigned to another one. + +=back + +=item * + +C<XS::Typemap> has been upgraded from version 0.04 to 0.05. + +=back + +=head1 Documentation + +=head2 Changes to Existing Documentation + +=head3 L<perlfunc> + +=over 4 + +=item * + +Clarified the order in which to check C<$@> and C<$!> after C<do FILE>. +(RT #80626) + +=back + +=head1 Diagnostics + +The following additions or changes have been made to diagnostic output, +including warnings and fatal error messages. For the complete list of +diagnostic messages, see L<perldiag>. + +=head2 New Diagnostics + +=over 4 + +=item * + +Regexp modifier "/%c" may not appear twice + +(F syntax) The regular expression pattern had one of the mutually exclusive +modifiers repeated. Remove all but one of the occurrences. + +=item * + +Regexp modifiers "/%c" and "/%c" are mutually exclusive + +(F syntax) The regular expression pattern had more than one of the mutually +exclusive modifiers. Retain only the modifier that is supposed to be there. + +=item * + +Insecure user-defined property %s + +(F) Perl detected tainted data when trying to compile a regular +expression that contains a call to a user-defined character property +function, i.e. C<\p{IsFoo}> or C<\p{InFoo}>. +See L<perlunicode/User-Defined Character Properties> and L<perlsec>. + +=back + +=head1 Testing + +Many of the tests have been refactored to use testing libraries more +consistently. In some cases test files were created or deleted: + +=over 4 + +=item * + +The tests for C<split /\s/> and Unicode have been moved from +F<t/op/split.t> to the new F<t/op/split_unicode.t>. + +=item * + +F<t/re/re.t> has been moved to F<ext/re/t/re_funcs_u.t>. + +=item * + +The tests for [perl #72922] have been moved from F<t/re/qr.t> to the new +F<t/re/qr-72922.t>. + +=item * + +F<t/re/reg_unsafe.t> has been deleted and its only test moved to +F<t/re/pat_advanced.t>. + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +A fix for a bug in C<length(undef)> in 5.13.4 introduced a regression that +meant C<print length undef> did not warn when warnings were enabled. It now +correctly warns [perl #85508]. + +=item * + +The C<(?|...)> regular expression construct no longer crashes if the final +branch has more sets of capturing parentheses than any other branch. This +was fixed in Perl 5.10.1 for the case of a single branch, but that fix did +not take multiple branches into account [perl #84746]. + +=item * + +Accessing an element of a package array with a hard-coded number (as +opposed to an arbitrary expression) would crash if the array did not exist. +Usually the array would be autovivified during compilation, but typeglob +manipulation could remove it, as in these two cases which used to crash: + + *d = *a; print $d[0]; + undef *d; print $d[0]; + +=item * + +C<#line> directives in string evals were not properly updating the arrays +of lines of code (C<< @{"_<..."} >>) that the debugger (or any debugging or +profiling module) uses. In threaded builds, they were not being updated at +all. In non-threaded builds, the line number was ignored, so any change to +the existing line number would cause the lines to be misnumbered +[perl #79442]. + +=item * + +C<$AUTOLOAD> used to remain tainted forever if it ever became tainted. Now +it is correctly untainted if an autoloaded method is called and the method +name was not tainted. + +=item * + +A bug has been fixed in the implementation of C<{...}> quantifiers in +regular expressions that prevented the code block in +C</((\w+)(?{ print $2 })){2}/> from seeing the C<$2> sometimes +[perl #84294]. + +=item * + +C<sprintf> now dies when passed a tainted scalar for the format. It did +already die for arbitrary expressions, but not for simple scalars +[perl #82250]. + +=item * + +DESTROY methods of objects implementing ties are no longer able to crash by +accessing the tied variable through a weak reference [perl #86328]. + +=item * + +On Windows, calling kill(9, $child) on a pseudo-process created by the fork() +emulation is inherently unstable. It can also be responsible for overriding +the parent process exit code with a value of '9' if the parent terminates +right after killing the child. This condition will now happen a lot less +often than before. + +See also L</"fork() emulation will not wait for signalled children"> for a +better way to terminate child processes that avoids deadlocks altogether. + +=item * + +Ensure that the C<exists &Errno::EFOO> idiom continues to work as documented. + +A change post-5.12 caused the documented idiom not to work if Errno was loaded +after the C<exists> code had been compiled, as the compiler implicitly creates +typeglobs in the Errno symbol table when it builds the optree for the C<exists +code>. + +=back + +=head1 Acknowledgements + +Perl 5.13.11 represents approximately one month of development since Perl +5.13.10 and contains approximately 80,000 lines of changes across 549 files from +31 authors and committers: + +Alastair Douglas, Arvan, Boris Ratner, brian d foy, Chris 'BinGOs' Williams, +Craig A. Berry, David Golden, David Leadbeater, David Mitchell, Father +Chrysostomos, Florian Ragwitz, Jan Dubois, Karl Williamson, Kevin Ryde, Leon +Brocard, Leon Timmermans, Michael Stevens, Michael Witten, Moritz Lenz, Nicholas +Clark, Paul Johnson, Peter John Acklam, Reini Urban, Robin Barker, Steve Hay, +Sullivan Beck, Tony Cook, Vadim Konovalov, Yves Orton, Zefram and Ævar Arnfjörð +Bjarmason + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the L<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5131delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5131delta.pod new file mode 100644 index 00000000000..1a372bfd6af --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5131delta.pod @@ -0,0 +1,287 @@ +=encoding utf8 + +=head1 NAME + +perl5131delta - what is new for perl v5.13.1 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.0 release and +the 5.13.1 release. + +If you are upgrading from an earlier release such as 5.10, first read +L<perl5120delta>, which describes differences between 5.10 and +5.12. + +=head1 Incompatible Changes + +=head2 "C<\cI<X>>" + +The backslash-c construct was designed as a way of specifying +non-printable characters, but there were no restrictions (on ASCII +platforms) on what the character following the C<c> could be. Now, that +character must be one of the ASCII characters. + +=head2 localised tied hashes, arrays and scalars are no longed tied + +In the following: + + tie @a, ...; + { + local @a; + # here, @a is a now a new, untied array + } + # here, @a refers again to the old, tied array + +The new local array used to be made tied too, which was fairly pointless, +and has now been fixed. This fix could however potentially cause a change +in behaviour of some code. + +=head2 C<given> return values + +Starting from this release, C<given> blocks returns the last evaluated +expression, or an empty list if the block was exited by C<break>. Thus you +can now write: + + my $type = do { + given ($num) { + break when undef; + 'integer' when /^[+-]?[0-9]+$/; + 'float' when /^[+-]?[0-9]+(?:\.[0-9]+)?$/; + 'unknown'; + } + }; + +See L<perlsyn/Return value> for details. + +=head1 Core Enhancements + +=head2 Exception Handling Reliability + +Several changes have been made to the way C<die>, C<warn>, and C<$@> +behave, in order to make them more reliable and consistent. + +When an exception is thrown inside an C<eval>, the exception is no +longer at risk of being clobbered by code running during unwinding +(e.g., destructors). Previously, the exception was written into C<$@> +early in the throwing process, and would be overwritten if C<eval> was +used internally in the destructor for an object that had to be freed +while exiting from the outer C<eval>. Now the exception is written +into C<$@> last thing before exiting the outer C<eval>, so the code +running immediately thereafter can rely on the value in C<$@> correctly +corresponding to that C<eval>. + +Likewise, a C<local $@> inside an C<eval> will no longer clobber any +exception thrown in its scope. Previously, the restoration of C<$@> upon +unwinding would overwrite any exception being thrown. Now the exception +gets to the C<eval> anyway. So C<local $@> is safe inside an C<eval>, +albeit of rather limited use. + +Exceptions thrown from object destructors no longer modify the C<$@> +of the surrounding context. (If the surrounding context was exception +unwinding, this used to be another way to clobber the exception being +thrown. Due to the above change it no longer has that significance, +but there are other situations where C<$@> is significant.) Previously +such an exception was sometimes emitted as a warning, and then either +string-appended to the surrounding C<$@> or completely replaced the +surrounding C<$@>, depending on whether that exception and the surrounding +C<$@> were strings or objects. Now, an exception in this situation is +always emitted as a warning, leaving the surrounding C<$@> untouched. +In addition to object destructors, this also affects any function call +performed by XS code using the C<G_KEEPERR> flag. + +C<$@> is also no longer used as an internal temporary variable when +preparing to C<die>. Previously it was internally necessary to put +any exception object (any non-string exception) into C<$@> first, +before it could be used as an exception. (The C API still offers the +old option, so an XS module might still clobber C<$@> in the old way.) +This change together with the foregoing means that, in various places, +C<$@> may be observed to contain its previously-assigned value, rather +than having been overwritten by recent exception-related activity. + +Warnings for C<warn> can now be objects, in the same way as exceptions +for C<die>. If an object-based warning gets the default handling, +of writing to standard error, it will of course still be stringified +along the way. But a C<$SIG{__WARN__}> handler will now receive an +object-based warning as an object, where previously it was passed the +result of stringifying the object. + +=head1 Modules and Pragmata + +=head2 Updated Modules + +=over + +=item C<Errno> + +The implementation of C<Errno> has been refactored to use about 55% less memory. +There should be no user-visible changes. + +=item Perl 4 C<.pl> libraries + +These historical libraries have been minimally modified to avoid using +C<$[>. This is to prepare them for the deprecation of C<$[>. + +=item C<B::Deparse> + +A bug has been fixed when deparsing a nextstate op that has both a +change of package (relative to the previous nextstate), or a change of +C<%^H> or other state, and a label. Previously the label was emitted +first, leading to syntactically invalid output because a label is not +permitted immediately before a package declaration, B<BEGIN> block, +or some other things. Now the label is emitted last. + +=back + +=head2 Removed Modules and Pragmata + +The following modules have been removed from the core distribution, and if +needed should be installed from CPAN instead. + +=over + +=item C<Class::ISA> + +=item C<Pod::Plainer> + +=item C<Switch> + +=back + +The removal of C<Shell> has been deferred until after 5.14, as the +implementation of C<Shell> shipped with 5.12.0 did not correctly issue the +warning that it was to be removed from core. + +=head1 New Documentation + +=over 4 + +=item perlgpl + +L<perlgpl> has been updated to contain GPL version 1, as is included in the +F<README> distributed with perl. + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +Naming a deprecated character in \N{...} will not leak memory. + +=item * + +FETCH is no longer called needlessly on some tied variables. + +=item * + +The trie runtime code should no longer allocate massive amounts of memory, +fixing #74484. + +=back + +=head1 Changed Internals + +=over 4 + +=item * + +The protocol for unwinding the C stack at the last stage of a C<die> +has changed how it identifies the target stack frame. This now uses +a separate variable C<PL_restartjmpenv>, where previously it relied on +the C<blk_eval.cur_top_env> pointer in the C<eval> context frame that +has nominally just been discarded. This change means that code running +during various stages of Perl-level unwinding no longer needs to take +care to avoid destroying the ghost frame. + +=item * + +The format of entries on the scope stack has been changed, resulting in a +reduction of memory usage of about 10%. In particular, the memory used by +the scope stack to record each active lexical variable has been halved. + +=item * + +Memory allocation for pointer tables has been changed. Previously +C<Perl_ptr_table_store> allocated memory from the same arena system as C<SV> +bodies and C<HE>s, with freed memory remaining bound to those arenas until +interpreter exit. Now it allocates memory from arenas private to the specific +pointer table, and that memory is returned to the system when +C<Perl_ptr_table_free> is called. Additionally, allocation and release are both +less CPU intensive. + +=item * + +A new function, Perl_magic_methcall has been added that wraps the setup needed +to call a magic method like FETCH (the existing S_magic_methcall function has +been renamed S_magic_methcall1). + +=back + +=head1 Deprecations + +The following items are now deprecated. + +=over 4 + +=item C<Perl_ptr_table_clear> + +C<Perl_ptr_table_clear> is no longer part of Perl's public API. Calling it now +generates a deprecation warning, and it will be removed in a future +release. + +=back + +=head1 Acknowledgements + +Perl 5.13.1 represents thirty days of development since Perl 5.13.0 and +contains 15390 lines of changes across 289 files from 34 authors and +committers. + +Thank you to the following for contributing to this release: + +Ævar Arnfjörð Bjarmason, Arkturuz, Chris 'BinGOs' Williams, Craig A. Berry, +Curtis Jewell, Dan Dascalescu, David Golden, David Mitchell, Father +Chrysostomos, Gene Sullivan, gfx, Gisle Aas, H.Merijn Brand, James E Keenan, +James Mastros, Jan Dubois, Jesse Vincent, Karl Williamson, Leon Brocard, +Lubomir Rintel (GoodData), Nicholas Clark, Philippe Bruhat (BooK), Rafael +Garcia-Suarez, Rainer Tammer, Ricardo Signes, Richard Soderberg, Robin Barker, +Ruslan Zakirov, Steffen Mueller, Todd Rinaldo, Tony Cook, Vincent Pit, Zefram + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5132delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5132delta.pod new file mode 100644 index 00000000000..082fa0f69bc --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5132delta.pod @@ -0,0 +1,409 @@ +=encoding utf8 + +=head1 NAME + +perl5132delta - what is new for perl v5.13.2 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.2 release and +the 5.13.1 release. + +If you are upgrading from an earlier release such as 5.10, first read +L<perl5120delta>, which describes differences between 5.10 and +5.12. + +=head1 Incompatible Changes + +=head2 localised tied scalars are tied again. + +The change in behaviour in 5.13.1 of localising tied scalar values has +been reverted to the existing 5.12.0 and earlier behaviour (the change for +arrays and hashes remains). + +=head2 Naming fixes in Policy_sh.SH may invalidate Policy.sh + +Several long-standing typos and naming confusions in Policy_sh.SH have +been fixed, standardizing on the variable names used in config.sh. + +This will change the behavior of Policy.sh if you happen to have been +accidentally relying on the Policy.sh incorrect behavior. We'd appreciate +feedback from anyone using Policy.sh to be sure nothing is broken by +this change (c1bd23). + +=head2 Stashes are now always defined + +C<defined %Foo::> now always returns true, even when no symbols have yet been +defined in that package. + +This is a side effect of removing a special case kludge in the tokeniser, +added for 5.10.0, to hide side effects of changes to the internal storage of +hashes that to drastically reduce their memory usage overhead. + +Calling defined on a stash has been deprecated since 5.6.0, warned on +lexicals since 5.6.0, and has warned for stashes (and other package +variables) since 5.12.0. C<defined %hash> has always exposed an +implementation detail - emptying a hash by deleting all entries from it does +not make C<defined %hash> false, hence C<defined %hash> is not valid code to +determine whether an arbitrary hash is empty. Instead, use the behaviour +that an empty C<%hash> always returns false in a scalar context. + +=head1 Core Enhancements + +=head2 Non-destructive substitution + +The substitution operator now supports a C</r> option that +copies the input variable, carries out the substitution on +the copy and returns the result. The original remains unmodified. + + my $old = 'cat'; + my $new = $old =~ s/cat/dog/r; + # $old is 'cat' and $new is 'dog' + +This is particularly useful with C<map>. See L<perlop> for more examples +(4f4d75, 000c65). + +=head2 package block syntax + +A package declaration can now contain a code block, in which case the +declaration is in scope only inside that block. So C<package Foo { ... }> +is precisely equivalent to C<{ package Foo; ... }>. It also works with +a version number in the declaration, as in C<package Foo 1.2 { ... }>. +See L<perlfunc> (434da3..36f77d, 702646). + +=head2 CLONE_PARAMS structure added to ease correct thread creation + +Modules that create threads should now create C<CLONE_PARAMS> structures +by calling the new function C<Perl_clone_params_new()>, and free them with +C<Perl_clone_params_del()>. This will ensure compatibility with any future +changes to the internals of the C<CLONE_PARAMS> structure layout, and that +it is correctly allocated and initialised. + +=head2 perl -h no longer recommends -w + +perl -h used to mark the -w option as recommended; since this option is +far less useful than it used to be due to lexical 'use warnings' and since +perl -h is primary a list and brief explanation of the command line switches, +the recommendation has now been removed (60eaec). + +=head1 Modules and Pragmata + +=head2 Updated Modules + +=head3 Locale-Codes 3.13 + +Locale::Country, Locale::Language and Locale::Currency were updated from +3.12 to 3.13 of the Locale-Codes distribution to include locale code changes +(e1137b). + +=head3 Thread-Semaphore 2.11 + +Added new methods -E<gt>down_nb() and -E<gt>down_force() at the suggestion +of Rick Garlick. + +Refactored methods to skip argument validation when no argument is supplied. + +(04febe, f06daa) + +=head3 CPAN.pm 1.94_57 + +=over 4 + +=item * release 1.94_57 + +=item * bugfix: treat modules correctly that are deprecated in perl 5.12. + +=item * bugfix: RT #57482 and #57788 revealed that configure_requires +implicitly assumed build_requires instead of normal requires. (Reported +by Andrew Whatson and Father Chrysostomos respectively) + +=item * testfix: solaris should run the tests without expect because (some?) +solaris have a broken expect + +=item * testfix: run tests with cache_metadata off to prevent spill over +effects from previous test runs + +=back + +(742adb) + +=head3 Hash::Util warning fix + +Hash::Util now enables "no warnings 'uninitialized'" to suppress spurious +warnings from undefined hash values (RT #74280). + +=head3 B::Deparse now handles 'no VERSION' + +The 'no 5.13.2' or similar form is now correctly handled by B::Deparse. + +=head3 IO::Socket doc additions + +getsockopt and setsockopt are now documented. + +=head3 B::Concise updated for OPpDEREF + +B::Concise marks rv2sv, rv2av and rv2hv ops with the new OPpDEREF flag +as "DREFed". + +=head3 File::Copy doc clarification + +An extra stanza was added explaining behaviours when the copy destination +already exists and is a directory. + +=head3 Multiple POD spelling fixes. + +Fixes were made to VMS::DCLsym, mro, Search::Dist, B::t::OptreeCheck +and UNIVERSAL. + +=head1 Changes to Existing Documentation + +=head2 Replace wrong tr/// table in perlebcdic.pod + +perlebcdic.pod contains a helpful table to use in tr/// to convert +between EBCDIC and Latin1/ASCII. Unfortunately, the table was the +inverse of the one it describes, though the code that used the table +worked correctly for the specific example given. + +The table has been changed to its inverse, and the sample code changed +to correspond, as this is easier for the person trying to follow the +instructions since deriving the old table is somewhat more complicated. + +The table has also been changed to hex from octal, as that is more the norm +these days, and the recipes in the pod altered to print out leading +zeros to make all the values the same length, as the table that they can +generate has them (5f26d5). + +=head2 Document tricks for user-defined casing + +perlunicode.pod now contains an explanation of how to override, mangle +and otherwise tweak the way perl handles upper, lower and other case +conversions on unicode data, and how to provide scoped changes to alter +one's own code's behaviour without stomping on anybody else (71648f). + +=head2 Document $# and $* as removed and clarify $#array usage + +$# and $* were both disabled as of perl5 version 10; this release adds +documentation to that effect, a description of the results of continuing +to try and use them, and a note explaining that $# can also function as a +sigil in the $#array form (7f315d2). + +=head2 INSTALL explicitly states the requirement for C89 + +This was already true but it's now Officially Stated For The Record (51eec7). + +=head2 No longer advertise Math::TrulyRandom + +This module hasn't been updated since 1996 so we can't recommend it any more +(83918a). + +=head2 perlfaq synchronised to upstream + +The FAQ has been updated to commit +37550b8f812e591bcd0dd869d61677dac5bda92c from the perlfaq repository +at git@github.com:briandfoy/perlfaq.git + +=head1 Performance Enhancements + +Only allocate entries for @_ on demand - this not only saves memory per +subroutine defined but should hopefully improve COW behaviour (77bac2). + +=head2 Multiple small improvements to threads + +The internal structures of threading now make fewer API calls and fewer +allocations, resulting in noticeably smaller object code. Additionally, +many thread context checks have been deferred so that they're only done +when required (although this is only possible for non-debugging builds). + +=head2 Size optimisations to SV and HV structures + +xhv_fill has been eliminated from struct xpvhv, saving 1 IV per hash and +on some systems will cause struct xpvhv to become cache aligned. To avoid +this memory saving causing a slowdown elsewhere, boolean use of HvFILL +now calls HvTOTALKEYS instead (which is equivalent) - so while the fill +data when actually required is now calculated on demand, the cases when +this needs to be done should be few and far between (f4431c .. fcd245). + +The order of structure elements in SV bodies has changed. Effectively, +the NV slot has swapped location with STASH and MAGIC. As all access to +SV members is via macros, this should be completely transparent. This +change allows the space saving for PVHVs documented above, and may reduce +the memory allocation needed for PVIVs on some architectures. + +=head2 Optimisation of regexp engine string comparison work + +The foldEQ_utf8 API function for case-insensitive comparison of strings (which +is used heavily by the regexp engine) was substantially refactored and +optimised - and its documentation much improved as a free bonus gift +(8b3587, e6226b). + +=head2 Memory consumption improvements to Exporter + +The @EXPORT_FAIL AV is no longer created unless required, hence neither is +the typeglob backing it - this saves about 200 bytes per Exporter using +package that doesn't use this functionality. + +=head1 Installation and Configuration Improvements + +=head2 Compilation improvements + +Fix CCINCDIR and CCLIBDIR for mingw64 cross compiler to correctly be under +$(CCHOME)\mingw\include and \lib rather than immediately below $(CCHOME). + +This means the 'incpath', 'libpth', 'ldflags', 'lddlflags' and +'ldflags_nolargefiles' values in Config.pm and Config_heavy.pl are now +set correctly (23ae7f). + +=head1 Selected Bug Fixes + +=over 4 + +=item * Timely cleanup of SVs that are cloned into a new thread but then +discovered to be orphaned (i.e. their owners are -not- cloned) (e42956) + +=item * Don't accidentally clone lexicals in scope within active stack frames in +the parent when creating a child thread (RT #73086) (05d04d). + +=item * Avoid loading feature.pm when 'no 5.13.2;' or similar is +encountered (faee19). + +=item * Trap invalid use of SvIVX on SVt_REGEXP when assertions are on +(e77da3) + +=item * Don't stamp on $DB::single, $DB::trace and $DB::signal if they +already have values when $^P is assigned to (RT #72422) (4c0f30). + +=item * chop now correctly handles perl's extended UTF-8 (RT #73246) (65ab92) + +=item * Defer signal handling when shared SV locks are held to avoid +deadlocks (RT #74868) (65c742). + +=item * glob() no longer crashes when %File::Glob:: is empty and +CORE::GLOBAL::glob isn't present (4984aa). + +=item * perlbug now always permits the sender address to be changed +before sending - if you were having trouble sending bug reports before +now, this should fix it, we hope (e6eb90). + +=item * Overloading now works properly in conjunction with tied +variables. What formerly happened was that most ops checked their +arguments for overloading I<before> checking for magic, so for example +an overloaded object returned by a tied array access would usually be +treated as not overloaded (RT #57012) (6f1401, ed3b9b, 6a5f8c .. 24328f). + +=item * Independently, a bug was fixed that prevented $tied-E<gt>() from +always calling FETCH correctly (RT #8438) (7c7501) + +=back + +=head1 Changed Internals + +=over 4 + +=item * The implementation of sv_dup_inc() has changed from a macro to a function. + +=item * + +The C<find_rundefsvoffset> function has been deprecated. It appeared that +its design was insufficient to reliably get the lexical C<$_> at run-time. + +Use the new C<find_rundefsv> function or the C<UNDERBAR> macro instead. +They directly return the right SV representing C<$_>, whether it's lexical +or dynamic (789bd8 .. 03d5bc). + +=item * + +The following new functions or macros have been added to the public API: +C<SvNV_nomg>, C<sv_2nv_flags>, C<find_rundefsv>. + +=item * + +The C<UNDERBAR> macro now calls C<find_rundefsv>. C<dUNDERBAR> is now a +noop but should still be used to ensure past and future compatibility. + +=item * + +The ibcmp_* functions have been renamed and are now called foldEQ, +foldEQ_locale and foldEQ_utf8 (e6226b). + +=back + +=head1 Deprecations + +The following items are now deprecated. + +=over 4 + +=item * + +Omitting a space between a regex pattern or pattern modifiers and the following +word is deprecated. For example, C<< m/foo/sand $bar >> will still be parsed +as C<< m/foo/s and $bar >> but will issue a warning. + +=back + +=head1 Platform Specific Notes + +=head2 Recent OpenBSDs now use perl's malloc + +OpenBSD E<gt> 3.7 has a new malloc implementation which is mmap based +and as such can release memory back to the OS; however for perl using +this malloc causes a substantial slowdown so we now default to using +perl's malloc instead (RT #75742) (9b58b5). + +=head1 Acknowledgements + +Perl 5.13.2 represents thirty days of development since Perl 5.13.1 (and +two days of waiting around while the release manager remembered where he +left his brain) and contains 3685 lines of changes across 194 files from +30 authors and committers. + +Thank you to the following for contributing to this release: + +Abigail, Andreas J. Koenig, Chas. Owens, Chris 'BinGOs' Williams, +Craig A. Berry, David Caldwell, David Golden, David Mitchell, +Father Chrysostomos, George Greer, H.Merijn Brand, Jerry D. Hedden, +Karl Williamson, Maik Hentsche, Matt S Trout, Nicholas Clark, Rafael +Garcia-Suarez, Ricardo Signes, Salvador Fandino, Salvador Ortiz Garcia, +Shlomi Fish, Sinan Unur, Sisyphus, Slaven Rezic, Sullivan Beck, Tony Cook, +Vincent Pit, Zefram, brian d foy, Ævar Arnfjörð Bjarmason + +Your humble release manager would like to specifically call out +Karl Williamson for making the tests a better place to be, and Shlomi +Fish for a passel of tiny incremental docfixes of the sort that don't get +made often enough. + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5133delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5133delta.pod new file mode 100644 index 00000000000..af03607adf6 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5133delta.pod @@ -0,0 +1,667 @@ +=encoding utf8 + +=head1 NAME + +perl5133delta - what is new for perl v5.13.3 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.3 release and +the 5.13.2 release. + +If you are upgrading from an earlier release such as 5.13.1, first read +L<perl5132delta>, which describes differences between 5.13.1 and +5.13.2. + +=head1 Core Enhancements + +=head2 \o{...} for octals + +There is a new escape sequence, C<"\o">, in double-quote-like contexts. +It must be followed by braces enclosing an octal number of at least one +digit. It interpolates as the character with an ordinal value equal to +the octal number. This construct allows large octal ordinals beyond the +current max of 0777 to be represented. It also allows you to specify a +character in octal which can safely be concatenated with other regex +snippets and which won't be confused with being a backreference to +a regex capture group. See L<perlre/Capture groups>. + +=head2 C<\N{I<name>}> and C<charnames> enhancements + +C<\N{}> and C<charnames::vianame> now know about the abbreviated +character names listed by Unicode, such as NBSP, SHY, LRO, ZWJ, etc., as +well as all the customary abbreviations for the C0 and C1 control +characters (such as ACK, BEL, CAN, etc.), as well as a few new variants +in common usage of some C1 full names. + +In the past, it was ineffective to override one of Perl's abbreviations +with your own custom alias. Now it works. + +You can also create a custom alias directly to the ordinal of a +character, known by C<\N{...}>, C<charnames::vianame()>, and +C<charnames::viacode()>. Previously, an alias had to be to an official +Unicode character name. This made it impossible to create an alias for +a code point that had no name, such as the ones reserved for private +use. So this change allows you to make more effective use of private +use characters. Only if there is no official name will +C<charnames::viacode()> return your custom one. + +See L<charnames> for details on all these changes. + +=head2 Uppercase X/B allowed in hexadecimal/binary literals + +Literals may now use either upper case C<0X...> or C<0B...> prefixes, +in addition to the already supported C<0x...> and C<0b...> +syntax. (RT#76296) (a674e8d, 333f87f) + +C, Ruby, Python and PHP already supported this syntax, and it makes +Perl more internally consistent. A round-trip with C<eval sprintf +"%#X", 0x10> now returns C<16> in addition to C<eval sprintf "%#x", +0x10>, which worked before. + +=head1 Incompatible Changes + +=head2 \400 - \777 + +Use of C<\400> - C<\777> in regexes in certain circumstances has given +different, anomalous behavior than their use in all other +double-quote-like contexts. Since 5.10.1, a deprecated warning message +has been raised when this happens. Now, all double-quote-like contexts +have the same behavior, namely to be equivalent to C<\x{100}> - +C<\x{1FF}>, with no deprecation warning. Use of these values in the +command line option C<"-0"> retains the current meaning to slurp input +files whole; previously, this was documented only for C<"-0777">. It is +recommended, however, because of various ambiguities, to use the new +C<\o{...}> construct to represent characters in octal. +(fa1639c..f6993e9). + +=head1 Deprecations + +=head2 Omitting a space between a regular expression and subsequent word + +Omitting a space between a regex pattern or pattern modifiers and the +following word is deprecated. Deprecation for regular expression +I<matches> was added in Perl 5.13.2. In this release, the deprecation +is extended to regular expression I<substitutions>. For example, +C<< s/foo/bar/sand $bar >> will still be parsed as +C<< s/foo/bar/s and $bar >> but will issue a warning. (aa78b66) + +=head2 Deprecation warning added for deprecated-in-core .pl libs + +This is a mandatory warning, not obeying -X or lexical warning bits. +The warning is modelled on that supplied by deprecate.pm for +deprecated-in-core .pm libraries. It points to the specific CPAN +distribution that contains the .pl libraries. The CPAN version, of +course, does not generate the warning. (0111154) + +=head1 Performance Enhancements + +There are several small optimizations to reduce CPU cache misses in various very +commonly used modules like C<warnings> and C<Carp> as well in accessing +file-handles for reading. + +=head1 Modules and Pragmata + +=head2 Updated Modules and Pragmata + +=over 4 + +=item C<autodie> + +Upgraded from version 2.06_01 to 2.10. + +=item C<charnames> + +Upgraded from version 1.08 to 1.10. + +C<viacode()> is now significantly faster. (f3227b7) + +=item C<lib> + +Upgraded from version 0.62 to 0.63. + +=item C<threads> + +Upgraded from version 1.77_02 to 1.77_03. + +=item C<threads::shared> + +Upgraded from version 1.33_01 to 1.33_02. + +=item C<warnings> + +Upgraded from version 1.09 to 1.10. + +Calling C<use warnings> without arguments is now significantly more efficient. +(8452af9) + +=item C<Archive::Extract> + +Upgraded from version 0.38 to 0.42. + +Updates since 0.38 include: a safe print method that guards +Archive::Extract from changes to $\; a fix to the tests when run in core +perl; support for TZ files; and a modification for the lzma logic to favour +IO::Uncompress::Unlzma (d7f8799) + +=item C<Archive::Tar> + +Upgraded from version 1.54 to 1.64. + +Important changes since 1.54 include: compatibility with busybox +implementations of tar; a fix so that C<write()> and C<create_archive()> +close only handles they opened; and a bug was fixed regarding the exit code +of extract_archive. (afabe0e) + +=item C<Attribute::Handlers> + +Upgraded from version 0.87 to 0.88. + +=item C<Compress::Raw::Bzip2> + +Upgraded from version 2.024 to 2.027. + +=item C<Compress::Raw::Zlib> + +Upgraded from version 2.024 to 2.027_01. + +=item C<Compress::Zlib> + +Upgraded from version 2.024 to 2.027. + +=item C<CPANPLUS> + +Upgraded from version 0.90 to 0.9007. + +Fixed the shell test to skip if test is not being run under a terminal; +resolved the issue where a prereq on Config would not be recognised as a +core module. (d4e225a) + +=item C<Digest::MD5> + +Upgraded from version 2.39 to 2.40. + +=item C<Digest::SHA> + +Upgraded from version 5.47 to 5.48. + +=item C<Exporter> + +Upgraded from version 5.64_02 to 5.64_03. + +Exporter no longer overrides C<$SIG{__WARN__}> (RT #74472) (9b86bb5) + +=item C<ExtUtils::CBuilder> + +Upgraded from version 0.27 to 0.2703. + +=item C<ExtUtils::Manifest> + +Upgraded from version 1.57 to 1.58. + +=item C<ExtUtils::ParseXS> + +Upgraded from version 2.2205 to 2.2206. + +=item C<File::Copy> + +Upgraded from version 2.19 to 2.20. + +Skips suid tests on a nosuid partition. These tests were being skipped on +OpenBSD, but nosuid partitions can exist on other systems too. Now it just +checks if it can create a suid directory, if not the tests are skipped. +Perl builds without errors in a nosuid /tmp with this patch. (cae9400) + +=item C<I18N::LangTags> + +Upgraded from version 0.35 to 0.35_01. + +=item C<IPC::Cmd> + +Upgraded from version 0.58 to 0.60. + +=item C<IPC::SysV> + +Upgraded from version 2.01 to 2.03. + +=item C<Locale::Maketext> + +Upgraded from version 1.14 to 1.15. + +Locale::Maketext guts have been merged back into the main module (87d86da) +and adds external cache support (ace47d6) + +=item C<Module::Build> + +Upgraded from version 0.3603 to 0.3607. + +=item C<Module::CoreList> + +Upgraded from version 2.34 to 2.36. + +=item C<Module::Load> + +Upgraded from version 0.16 to 0.18. + +=item C<Term::ANSIColor> + +Upgraded from version 2.02 to 3.00. + +=item C<Test::Harness> + +Upgraded from version 3.17 to 3.21. + +The core update from Test-Harness 3.17 to 3.21 fixed some things, but +also L<introduced a known problem|/"Known Problems"> with argument +passing to non-Perl tests. + +=item C<Time::HiRes> + +Upgraded from version 1.9719 to 1.9721. + +=item C<Time::Piece> + +Upgraded from version 1.15_01 to 1.20_01. + +=item C<Unicode::Collate> + +Upgraded from version 0.52_01 to 0.53. + +Includes Unicode Collation Algorithm 18 (74b94a7) + +=item C<Unicode::Normalize> + +Upgraded from version 1.03 to 1.06. + +=back + +=head1 Documentation + +=head2 New Documentation + +=head3 L<perl5121delta> + +The Perl 5.12.1 perldelta file was added from the Perl maintenance branch + +=head2 Changes to Existing Documentation + +=head3 General changes + +=over + +=item * + +Octal character escapes in documentation now prefer a three-digit octal +escape or the new C<\o{...}> escape as they have more consistent behavior +in different contexts than other forms. (ce7b6f0) (d8b950d) (e1f120a) + +=item * + +Documentation now standardizes on the term 'capture group' over 'buffer' +in regular expression documentation (c27a5cf) + +=back + +=head3 L<perlfunc> + +=over + +=item * + +Added cautionary note about "no VERSION" (e0de7c2) + +=item * + +Added additional notes regarding srand when forking (d460397) + +=back + +=head3 L<perlop> + +=over 4 + +=item * + +Improved documentation of unusual character escapes (4068718, 9644846) + +=item * + +Clarified how hexadecimal escapes are interpreted, with particular +attention to the treatment of invalid characters (9644846) + +=back + +=head3 L<perlrun> + +=over + +=item * + +Clarified the behavior of the C<-0NNN> switch for C<-0400> or higher (7ba31cb) + +=back + +=head3 L<perlpolicy> + +=over + +=item * + +Added the policy on compatibility and deprecation along with definitions of +terms like "deprecation" (70e4a83) + +=back + +=head3 L<perlre> + +=over + +=item * + +Added examples of the perils of not using \g{} when there are more +than nine back-references (9d86067) + +=back + +=head3 L<perltie> + +=over + +=item * + +Updated some examples for modern Perl style (67d00dd) + +=back + +=head1 Utility Changes + +=head3 L<perldb> + +=over + +=item * + +The remote terminal works after forking and spawns new sessions - one +for each forked process (11653f7) + +=item * + +Uses the less pager path from Config instead of searching for it (bf320d6) + +=back + +=head1 Configuration and Compilation + +=over 4 + +=item * + +Adjusted 'make test.valgrind' to account for cpan/dist/ext separation +(e07ce2e) + +=back + +=head1 Testing + +=over 4 + +=item * + +F<t/harness> clears PERL5LIB, PERLLIB, PERL5OPT as t/TEST does (a2d3de1) + +=item * + +Many common testing routines were refactored into t/lib/common.pl + +=item * + +Several test files have been modernized to use Test::More + +=back + +=head1 Platform Support + +=head2 Discontinued Platforms + +=over 4 + +=item MacOS Classic + +Support for MacOS Classic within ExtUtils::MakeMaker was removed from Perl in +December 2004. Vestigial MacOS Classic specific code has now been removed +from other core modules as well (8f8c2a4..c457df0) + +=back + +=head2 Platform-Specific Notes + +=over 4 + +=item Win32 + +t/io/openpid.t now uses the alarm() watchdog strategy for more +robustness (5732108) + +=back + +=head1 Internal Changes + +=over 4 + +=item * + +Under some circumstances, the C<CvGV()> field of a CV is now reference +counted. To ensure consistent behaviour, direct assignment to it, for +example C<CvGV(cv) = gv> is now a compile-time error. A new macro, +C<CvGV_set(cv,gv)> has been introduced to perform this operation safely. +Note that modification of this field is not part of of the public API, +regardless of this new macro. This change caused some +L<issues|/"Known Problems"> in modules that used the private C<GvGV()> +field. + +=item * + +It is now possible for XS code to hook into Perl's lexical scope +mechanism at compile time, using the new C<Perl_blockhook_register> +function. See L<perlguts/"Compile-time scope hooks">. + +=item * + +Added C<Perl_croak_no_modify()> to implement +C<Perl_croak("%s", PL_no_modify)> (6ad8f25) + +=item * + +Added prototypes for C<tie()> and C<untie()> to allow overloading (RT#75902) +(1db4d19) + +=item * + +Adds C<my_[l]stat_flags()> to replace C<my_[l]stat()>. C<my_stat()> and +C<my_lstat()> call get magic on the stack arg, so create C<_flags()> +variants that allow us to control this. (0d7d409) + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +Some work has been done on the internal pointers that link between symbol +tables (stashes), typeglobs and subroutines. This has the effect that +various edge cases related to deleting stashes or stash entries (e.g. +<%FOO:: = ()>), and complex typeglob or code reference aliasing, will no +longer crash the interpreter. + +=item * + +Fixed readline() when interrupted by signals so it no longer returns +the "same thing" as before or random memory + +=item * + +Fixed a regression of kill() when a match variable is used for the +process ID to kill (RT#75812) (8af710e) + +=item * + +Fixed several subtle bugs in sort() when @_ is accessed within a subroutine +used for sorting (RT#72334) (8f443ca) + +=item * + +Catch yyparse() exceptions in C<< (?{...}) >> (RT#2353) (634d691) + +=item * + +Avoid UTF-8 cache panics with offsets beyond a string (RT #75898) (3e2d381) + +=item * + +Fixed POSIX::strftime memory leak (RT#73520) (c4bc4aa) + +=item * + +Doesn't set strict with C<no VERSION> if C<VERSION> is greater than 5.12 +(da8fb5d) + +=item * + +Avoids multiple FETCH/stringify on filetest ops (40c852d) + +=item * + +Fixed issue with string C<eval> not detecting taint of overloaded/tied +arguments (RT #75716) (895b760) + +=item * + +Fix potential crashes of string C<eval> when evaluating a object with +overloaded stringification by creating a stringified copy when necessary +(3e5c018) + +=item * + +Fixed bug where overloaded stringification could remove tainting +(RT #75716) (a02ec77) + +=item * + +Plugs more memory leaks in vms.c. (9e2bec0) + +=item * + +Fix pthread include error for Time::Piece (e9f284c) + +=back + +=head1 Known Problems + +=over 4 + +=item * + +Bug fixes involving CvGV reference counting break Sub::Name. A +patch has been sent upstream to the maintainer + +=item * + +readline() returns an empty string instead of undef when it is +interrupted by a signal + +=item * + +Test-Harness was updated from 3.17 to 3.21 for this release. A rewrite +in how it handles non-Perl tests (in 3.17_01) broke argument passing to +non-Perl tests with L<prove> (RT #59186), and required that non-Perl +tests be run as C<prove ./test.sh> instead of C<prove test.sh> These +issues are being solved upstream, but didn't make it into this release. +They're expected to be fixed in time for perl v5.13.4. (RT #59457) + +=item * + +C<version> now prevents object methods from being called as class methods +(d808b68) + +=back + +=head1 Errata + +=over 4 + +=item * + +Retroactively added the Acknowledgements list to L<perl5132delta>, +which was excluded in the original release (d1e2db0) + +=back + +=head1 Acknowledgements + +Perl 5.13.3 represents approximately one month of development since Perl +5.13.2, and contains 12,184 lines of changes across 575 files from 104 +authors and committers. + +Thank you to the following for contributing to this release: + +Abhijit Menon-Sen, Abigail, Alex Davies, Alex Vandiver, Alexandr +Ciornii, Andreas J. Koenig, Andrew Rodland, Andy Dougherty, Aristotle +Pagaltzis, Arkturuz, Ben Morrow, Bo Borgerson, Bo Lindbergh, Brad +Gilbert, Bram, Brian Phillips, Chas. Owens, Chip Salzenberg, Chris +Williams, Craig A. Berry, Curtis Jewell, Dan Dascalescu, Daniel +Frederick Crisman, Dave Rolsky, David Caldwell, David E. Wheeler, David +Golden, David Leadbeater, David Mitchell, Dennis Kaarsemaker, Eric +Brine, Father Chrysostomos, Florian Ragwitz, Frank Wiegand, Gene +Sullivan, George Greer, Gerard Goossen, Gisle Aas, Goro Fuji, Graham +Barr, H.Merijn Brand, Harmen, Hugo van der Sanden, James E Keenan, James +Mastros, Jan Dubois, Jerry D. Hedden, Jesse Vincent, Jim Cromie, John +Peacock, Jos Boumans, Josh ben Jore, Karl Williamson, Kevin Ryde, Leon +Brocard, Lubomir Rintel, Maik Hentsche, Marcus Holland-Moritz, Matt +Johnson, Matt S Trout, Max Maischein, Michael Breen, Michael G Schwern, +Moritz Lenz, Nga Tang Chan, Nicholas Clark, Nick Cleaton, Nick Johnston, +Niko Tyni, Offer Kaye, Paul Marquess, Philip Hazel, Philippe Bruhat, +Rafael Garcia-Suarez, Rainer Tammer, Reini Urban, Ricardo Signes, +Richard Soderberg, Robin Barker, Ruslan Zakirov, Salvador Fandino, +Salvador Ortiz Garcia, Shlomi Fish, Sinan Unur, Sisyphus, Slaven Rezic, +Steffen Mueller, Stepan Kasal, Steve Hay, Steve Peters, Sullivan Beck, +Tim Bunce, Todd Rinaldo, Tom Christiansen, Tom Hukins, Tony Cook, +Vincent Pit, Yuval Kogman, Yves Orton, Zefram, brian d foy, chromatic, +kmx, Ævar Arnfjörð Bjarmason + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5134delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5134delta.pod new file mode 100644 index 00000000000..e90fbffeb9b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5134delta.pod @@ -0,0 +1,542 @@ +=encoding utf8 + +=head1 NAME + +perl5134delta - what is new for perl v5.13.4 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.4 release and +the 5.13.3 release. + +If you are upgrading from an earlier release such as 5.13.2, first read +L<perl5133delta>, which describes differences between 5.13.2 and +5.13.3. + +=head1 Core Enhancements + +=head2 C<srand()> now returns the seed + +This allows programs that need to have repeatable results to not have to come +up with their own seed generating mechanism. Instead, they can use C<srand()> +and somehow stash the return for future use. Typical is a test program which +has too many combinations to test comprehensively in the time available to it +each run. It can test a random subset each time, and should there be a failure, +log the seed used for that run so that it can later be used to reproduce the +exact results. + +=head2 C<\N{I<name>}> and C<charnames> enhancements + +C<\N{}>, C<charnames::vianame>, C<charnames::viacode> now know about every +character in Unicode. Previously, they didn't know about the Hangul syllables +nor a number of CJK (Chinese/Japanese/Korean) characters. + +=head1 Incompatible Changes + +=head2 Declare API incompatibility between blead releases + +Only stable releases (5.10.x, 5.12.x, 5.14.x, ...) guarantee binary +compatibility with each other, while blead releases (5.13.x, 5.15.x, ...) often +break this compatibility. However, prior to perl 5.13.4, all blead releases had +the same C<PERL_API_REVISION>, C<PERL_API_VERSION>, and C<PERL_API_SUBVERSION>, +effectively declaring them as binary compatible, which they weren't. From now +on, blead releases will have a C<PERL_API_SUBVERSION> equal to their +C<PERL_SUBVERSION>, explicitly marking them as incompatible with each other. + +Maintenance releases of stable perl versions will continue to make no +intentionally incompatible API changes. + +=head2 Check API compatibility when loading XS modules + +When perl's API changes in incompatible ways (which usually happens between +every major release), XS modules compiled for previous versions of perl will not +work anymore. They will need to be recompiled against the new perl. + +In order to ensure that modules are recompiled, and to prevent users from +accidentally loading modules compiled for old perls into newer ones, the +C<XS_APIVERSION_BOOTCHECK> macro has been added. That macro, which is called +when loading every newly compiled extension, compares the API version of the +running perl with the version a module has been compiled for and raises an +exception if they don't match. + +=head2 Binary Incompatible with all previous Perls + +Some bit fields have been reordered; therefore, this release will not be binary +compatible with any previous Perl release. + +=head2 Change in the parsing of certain prototypes + +Functions declared with the following prototypes now behave correctly as unary +functions: + +=over 4 + +=item * + +C<*> + +=item * + +C<\sigil> + +=item * + +C<\[...]> + +=item * + +C<;$> + +=item * + +C<;*> + +=item * + +C<;\sigil> + +=item * + +C<;\[...]> + +=back + +Due to this bug fix, functions using the C<(*)>, C<(;$)> and C<(;*)> prototypes +are parsed with higher precedence than before. So in the following example: + + sub foo($); + foo $a < $b; + +the second line is now parsed correctly as C<< foo($a) < $b >>, rather than +C<< foo($a < $b) >>. This happens when one of these operators is used in +an unparenthesised argument: + + < > <= >= lt gt le ge + == != <=> eq ne cmp ~~ + & + | ^ + && + || // + .. ... + ?: + = += -= *= etc. + +=head1 Deprecations + +=head2 List assignment to C<$[> + +After assignment to C<$[> has been deprecated and started to give warnings in +perl version 5.12.0, this version of perl also starts to emit a warning when +assigning to C<$[> in list context. This fixes an oversight in 5.12.0. + +=head1 Performance Enhancements + +=over 4 + +=item * + +Make string appending 100 times faster + +When doing a lot of string appending, perl could end up allocating a lot more +memory than needed in a very inefficient way, if perl was configured to use the +system's C<malloc> implementation instead of its own. + +C<sv_grow>, which is what's being used to allocate more memory if necessary when +appending to a string, has now been taught how to round up the memory it +requests to a certain geometric progression, making it much faster on certain +platforms and configurations. On Win32, it's now about 100 times faster. + +=item * + +For weak references, the common case of just a single weak reference per +referent has been optimised to reduce the storage required. In this case it +saves the equivalent of one small perl array per referent. + +=item * + +C<XPV>, C<XPVIV>, and C<XPVNV> now only allocate the parts of the C<SV> body +they actually use, saving some space. + +=back + +=head1 Modules and Pragmata + +=head2 New Modules and Pragmata + +This release does not introduce any new modules or pragmata. + +=head2 Updated Modules and Pragmata + +=over 4 + +=item C<Archive::Tar> + +Upgraded from version 1.64 to 1.68. + +Among other things, the new version adds a new option to C<ptar> to allow safe +creation of tarballs without world-writable files on Windows, allowing those +archives to be uploaded to CPAN. + +=item C<B::Lint> + +Upgraded from version 1.11 to 1.12. + +=item C<Carp> + +Upgraded from version 1.16 to 1.18. + +L<Carp> now detects incomplete L<caller()|perlfunc/"caller EXPR"> overrides and +avoids using bogus C<@DB::args>. To provide backtraces, Carp relies on +particular behaviour of the caller built-in. Carp now detects if other code has +overridden this with an incomplete implementation, and modifies its backtrace +accordingly. Previously incomplete overrides would cause incorrect values in +backtraces (best case), or obscure fatal errors (worst case) + +This fixes certain cases of C<Bizarre copy of ARRAY> caused by modules +overriding C<caller()> incorrectly. + +=item C<Compress::Raw::Bzip2> + +Upgraded from version 2.027 to 2.030. + +=item C<Compress::Raw::Zlib> + +Upgraded from version 2.027 to 2.030. + +=item C<File::Spec> + +Upgraded from version 3.31 to 3.31_01. + +Various issues in L<File::Spec::VMS> have been fixed. + +=item C<I18N::Langinfo> + +Upgraded from version 0.03 to 0.04. + +C<langinfo()> now defaults to using C<$_> if there is no argument given, just +like the documentation always claimed it did. + +=item C<IO::Compress> + +Upgraded from version 2.027 to 2.030. + +=item C<Module::CoreList> + +Upgraded from version 2.36 to 2.37. + +Besides listing the updated core modules of this release, it also stops listing +the C<Filespec> module. That module never existed in core. The scripts +generating C<Module::CoreList> confused it with C<VMS::Filespec>, which actually +is a core module, since the time of perl 5.8.7. + +=item C<Test::Harness> + +Upgraded from version 3.21 to 3.22. + +=item C<Test::Simple> + +Upgraded from version 0.94 to 0.96. + +Among many other things, subtests without a C<plan> or C<no_plan> now have an +implicit C<done_testing()> added to them. + +=item C<Unicode::Collate> + +Upgraded from version 0.53 to 0.56. + +Among other things, it is now using UCA Revision 20 (based on Unicode 5.2.0) and +supports a couple of new locales. + +=item C<feature> + +Upgraded from version 1.17 to 1.18. + +=back + +=head2 Removed Modules and Pragmata + +This release does not remove any modules or pragmata. + +=head1 Documentation + +=head2 Changes to Existing Documentation + +=head3 L<perldiag> + +=over 4 + +=item * + +The following existing diagnostics are now documented: + +=over 4 + +=item * + +L<Ambiguous use of %c resolved as operator %c|perldiag/"Ambiguous use of %c resolved as operator %c"> + +=item * + +L<Ambiguous use of %c{%s} resolved to %c%s|perldiag/"Ambiguous use of %c{%s} resolved to %c%s"> + +=item * + +L<Ambiguous use of %c{%s%s} resolved to %c%s%s|perldiag/"Ambiguous use of %c{%s%s} resolved to %c%s%s"> + +=item * + +L<Ambiguous use of -%s resolved as -&%s()|perldiag/"Ambiguous use of -%s resolved as -&%s()"> + +=item * + +L<Invalid strict version format (%s)|perldiag/"Invalid strict version format (%s)"> + +=item * + +L<Invalid version format (%s)|perldiag/"Invalid version format (%s)"> + +=item * + +L<Invalid version object|perldiag/"Invalid version object"> + +=back + +=back + +=head3 L<perlport> + +=over 4 + +=item * + +Documented a L<limitation|perlport/alarm> of L<alarm()|perlfunc/"alarm SECONDS"> +on Win32. + +=back + +=head3 L<perlre> + +=over 4 + +=item * + +Minor fix to a multiple scalar match example. + +=back + +=head1 Configuration and Compilation + +=over 4 + +=item * + +Compatibility with C<C++> compilers has been improved. + +=item * + +On compilers that support it, C<-Wwrite-strings> is now added to cflags by +default. + +=back + +=head1 Testing + +=over 4 + +=item * + +F<t/op/print.t> has been added to test implicit printing of C<$_>. + +=item * + +F<t/io/errnosig.t> has been added to test for restoration of of C<$!> when +leaving signal handlers. + +=item * + +F<t/op/tie_fetch_count.t> has been added to see if C<FETCH> is only called once +on tied variables. + +=item * + +F<lib/Tie/ExtraHash.t> has been added to make sure the, previously untested, +L<Tie::ExtraHash> keeps working. + +=item * + +F<t/re/overload.t> has been added to test against string corruption in pattern +matches on overloaded objects. This is a TODO test. + +=back + +=head1 Platform Support + +=head2 Platform-Specific Notes + +=over 4 + +=item Win32 + +=over 4 + +=item * + +Fixed a possible hang in F<t/op/readline.t>. + +=item * + +Fixed build process for SDK2003SP1 compilers. + +=item * + +When using old 32-bit compilers, the define C<_USE_32BIT_TIME_T> will now be set +in C<$Config{ccflags}>. This improves portability when compiling XS extensions +using new compilers, but for a perl compiled with old 32-bit compilers. + +=back + +=back + +=head1 Internal Changes + +=over 4 + +=item Removed C<PERL_POLLUTE> + +The option to define C<PERL_POLLUTE> to expose older 5.005 symbols for backwards +compatibility has been removed. It's use was always discouraged, and MakeMaker +contains a more specific escape hatch: + + perl Makefile.PL POLLUTE=1 + +This can be used for modules that have not been upgraded to 5.6 naming +conventions (and really should be completely obsolete by now). + +=item Added C<PERL_STATIC_INLINE> + +The C<PERL_STATIC_INLINE> define has been added to provide the best-guess +incantation to use for static inline functions, if the C compiler supports +C99-style static inline. If it doesn't, it'll give a plain C<static>. + +C<HAS_STATIC_INLINE> can be used to check if the compiler actually supports +inline functions. + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +A possible memory leak when using L<caller()|perlfunc/"caller EXPR"> to set +C<@DB::args> has been fixed. + +=item * + +Several memory leaks when loading XS modules were fixed. + +=item * + +A panic in the regular expression optimizer has been fixed (RT#75762). + +=item * + +Assignments to lvalue subroutines now honor copy-on-write behavior again, which +has been broken since version 5.10.0 (RT#75656). + +=item * + +Assignments to glob copies now behave just like assignments to regular globs +(RT#1804). + +=item * + +Within signal handlers, C<$!> is now implicitly localized. + +=item * + +L<readline|perlfunc/"readline EXPR"> now honors C<< <> >> overloading on tied +arguments. + +=item * + +L<substr()|perlfunc/"substr EXPR,OFFSET,LENGTH,REPLACEMENT">, +L<pos()|perlfunc/"index STR,SUBSTR,POSITION">, L<keys()|perlfunc/"keys HASH">, +and L<vec()|perlfunc/"vec EXPR,OFFSET,BITS"> could, when used in combination +with lvalues, result in leaking the scalar value they operate on, and cause its +destruction to happen too late. This has now been fixed. + +=item * + +Building with C<PERL_GLOBAL_STRUCT>, which has been broken accidentally in +5.13.3, now works again. + +=back + +=head1 Known Problems + +=over 4 + +=item * + +The changes in L<substr()|perlfunc/"substr EXPR,OFFSET,LENGTH,REPLACEMENT"> +broke C<HTML::Parser> <= 3.66. A fixed C<HTML::Parser> is available as version +3.67 on CPAN. + +=item * + +The changes in prototype handling break C<Switch>. A patch has been sent +upstream and will hopefully appear on CPAN soon. + +=back + +=head1 Acknowledgements + +Perl 5.13.4 represents approximately one month of development since Perl 5.13.3, +and contains 91,200 lines of changes across 436 files from 34 authors and +committers. + +Thank you to the following for contributing to this release: + +Abigail, Andy Armstrong, Andy Dougherty, Chas. Owens, Chip Salzenberg, Chris +'BinGOs' Williams, Craig A. Berry, David Cantrell, David Golden, David Mitchell, +Eric Brine, Father Chrysostomos, Florian Ragwitz, George Greer, Gerard Goossen, +H.Merijn Brand, James Mastros, Jan Dubois, Jerry D. Hedden, Joshua ben Jore, +Karl Williamson, Lars Dɪᴇᴄᴋá´á´¡ 迪拉斯, Leon Brocard, Lubomir Rintel, Nicholas +Clark, Paul Marquess, Rafael Garcia-Suarez, Reini Urban, Robin Barker, Slaven +Rezic, Steve Peters, Tony Cook, Wolfram Humann, Zefram + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles recently +posted to the comp.lang.perl.misc newsgroup and the perl bug database at +http://rt.perl.org/perlbug/ . There may also be information at +http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> program +included with your release. Be sure to trim your bug down to a tiny but +sufficient test case. Your bug report, along with the output of C<perl -V>, +will be sent off to perlbug@perl.org to be analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send it +to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able to +help assess the impact of issues, figure out a resolution, and help co-ordinate +the release of patches to mitigate or fix the problem across all platforms on +which Perl is supported. Please only use this address for security issues in the +Perl core, not for modules independently distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5135delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5135delta.pod new file mode 100644 index 00000000000..de76d586bd7 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5135delta.pod @@ -0,0 +1,592 @@ +=encoding utf8 + +=head1 NAME + +perl5135delta - what is new for perl v5.13.5 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.4 release and +the 5.13.5 release. + +If you are upgrading from an earlier release such as 5.13.3, first read +L<perl5134delta>, which describes differences between 5.13.3 and +5.13.4. + +=head1 Core Enhancements + +=head2 Adjacent pairs of nextstate opcodes are now optimized away + +Previously, in code such as + + use constant DEBUG => 0; + + sub GAK { + warn if DEBUG; + print "stuff\n"; + } + +the ops for C<warn if DEBUG;> would be folded to a C<null> op (C<ex-const>), but +the C<nextstate> op would remain, resulting in a runtime op dispatch of +C<nextstate>, C<nextstate>, ... + +The execution of a sequence of C<nextstate> ops is indistinguishable from just +the last C<nextstate> op so the peephole optimizer now eliminates the first of +a pair of C<nextstate> ops, except where the first carries a label, since labels +must not be eliminated by the optimizer and label usage isn't conclusively known +at compile time. + +=head2 API function to parse statements + +The C<parse_fullstmt> function has been added to allow parsing of a single +complete Perl statement. See L<perlapi> for details. + +=head2 API functions for accessing the runtime hinthash + +A new C API for introspecting the hinthash C<%^H> at runtime has been added. +See C<cop_hints_2hv>, C<cop_hints_fetchpvn>, C<cop_hints_fetchpvs>, +C<cop_hints_fetchsv>, and C<hv_copy_hints_hv> in L<perlapi> for details. + +=head2 C interface to C<caller()> + +The C<caller_cx> function has been added as an XSUB-writer's equivalent of +C<caller()>. See L<perlapi> for details. + +=head1 Incompatible Changes + +=head2 Magic variables outside the main package + +In previous versions of Perl, magic variables like C<$!>, C<%SIG>, etc. would +'leak' into other packages. So C<%foo::SIG> could be used to access signals, +C<${"foo::!"}> (with strict mode off) to access C's C<errno>, etc. + +This was a bug, or an 'unintentional' feature, which caused various ill effects, +such as signal handlers being wiped when modules were loaded, etc. + +This has been fixed (or the feature has been removed, depending on how you see +it). + +=head2 Smart-matching against array slices + +Previously, the following code resulted in a successful match: + + my @a = qw(a y0 z); + my @b = qw(a x0 z); + @a[0 .. $#b] ~~ @b; + +This odd behaviour has now been fixed +L<[perl #77468]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=77468>. + +=head2 C API changes + +The first argument of the C API function C<Perl_fetch_cop_label> has changed +from C<struct refcounted he *> to C<COP *>, to better insulate the user from +implementation details. + +This API function was marked as "may change", and likely isn't in use outside +the core. (Neither an unpacked CPAN, nor Google's codesearch, finds any other +references to it.) + +=head1 Deprecations + +=head2 Use of qw(...) as parentheses + +Historically the parser fooled itself into thinking that C<qw(...)> literals +were always enclosed in parentheses, and as a result you could sometimes omit +parentheses around them: + + for $x qw(a b c) { ... } + +The parser no longer lies to itself in this way. Wrap the list literal in +parentheses, like: + + for $x (qw(a b c)) { ... } + +=head1 Performance Enhancements + +=over 4 + +=item * + +Scalars containing regular expressions now only allocate the part of the C<SV> +body they actually use, saving some space. + +=item * + +Compiling regular expressions has been made faster for the case where upgrading +the regex to utf8 is necessary but that isn't known when the compilation begins. + +=back + +=head1 Modules and Pragmata + +=head2 Updated Modules and Pragmata + +=over 4 + +=item C<bignum> + +Upgraded from version 0.23 to 0.25. + +=item C<blib> + +Upgraded from version 1.05 to 1.06. + +=item C<open> + +Upgraded from version 1.07 to 1.08. + +=item C<threads-shared> + +Upgraded from version 1.33_02 to 1.33_03. + +=item C<warnings> and C<warnings::register> + +Upgraded from version 1.10 to 1.11 and from version 1.01 to 1.02 respectively. + +It is now possible to register warning categories other than the names of +packages using C<warnings::register>. See L<perllexwarn> for more information. + +=item C<B::Debug> + +Upgraded from version 1.12 to 1.16. + +=item C<CPANPLUS::Dist::Build> + +Upgraded from version 0.46 to 0.48. + +=item C<Data::Dumper> + +Upgraded from version 2.126 to 2.128. + +This fixes a crash when using custom sort functions that might cause the stack +to change. + +=item C<Encode> + +Upgraded from version 2.39 to 2.40. + +=item C<Errno> + +Upgraded from version 1.12 to 1.13. + +On some platforms with unusual header files, like Win32/gcc using mingw64 +headers, some constants which weren't actually error numbers have been exposed +by C<Errno>. This has been fixed +L<[perl #77416]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=77416>. + +=item C<ExtUtils::MakeMaker> + +Upgraded from version 6.5601 to 6.57_05. + +=item C<Filter::Simple> + +Upgraded from version 0.84 to 0.85. + +=item C<Hash::Util> + +Upgraded from version 0.08 to 0.09. + +=item C<Math::BigInt> + +Upgraded from version 1.89_01 to 1.95. + +This fixes, among other things, incorrect results when computing binomial +coefficients +L<[perl #77640]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77640>. + +=item C<Math::BigInt::FastCalc> + +Upgraded from version 0.19 to 0.22. + +=item C<Math::BigRat> + +Upgraded from version 0.24 to 0.26. + +=item C<Module::CoreList> + +Upgraded from version 2.37 to 2.38. + +=item C<PerlIO::scalar> + +Upgraded from version 0.08 to 0.09. + +=item C<POSIX> + +Upgraded from version 1.19 to 1.20. + +It now includes constants for POSIX signal constants. + +=item C<Safe> + +Upgraded from version 2.27 to 2.28. + +This fixes a possible infinite loop when looking for coderefs. + +=item C<Test::Simple> + +Upgraded from version 0.96 to 0.97_01. + +=item C<Tie::Hash> + +Upgraded from version 1.03 to 1.04. + +Calling C<< Tie::Hash-E<gt>TIEHASH() >> used to loop forever. Now it C<croak>s. + +=item C<Unicode::Collate> + +Upgraded from version 0.56 to 0.59. + +=item C<XSLoader> + +Upgraded from version 0.10 to 0.11. + +=back + +=head1 Documentation + +=head2 Changes to Existing Documentation + +=head3 L<perlapi> + +=over 4 + +=item * + +Many of the optree construction functions are now documented. + +=back + +=head3 L<perlbook> + +=over 4 + +=item * + +Expanded to cover many more popular books. + +=back + +=head3 L<perlfaq> + +=over 4 + +=item * + +L<perlfaq>, L<perlfaq2>, L<perlfaq4>, L<perlfaq5>, L<perlfaq6>, L<perlfaq8>, and +L<perlfaq9> have seen various updates and modernizations. + +=back + +=head1 Diagnostics + +The following additions or changes have been made to diagnostic output, +including warnings and fatal error messages. For the complete list of +diagnostic messages, see L<perldiag>. + +=head2 New Diagnostics + +=over 4 + +=item * + +Parsing code internal error (%s) + +New fatal error produced when parsing code supplied by an extension violated the +parser's API in a detectable way. + +=item * + +Use of qw(...) as parentheses is deprecated + +See L</"Use of qw(...) as parentheses"> for details. + +=back + +=head2 Changes to Existing Diagnostics + +=over 4 + +=item * + +C<warn> and C<die> now produce 'Wide character' warnings when fed a +character outside the byte range if STDERR is a byte-sized handle. + +=back + +=head1 Utility Changes + +=head3 L<h2ph> + +=over 4 + +=item * + +The use of a deprecated C<goto> construct has been removed +L<[perl #74404]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=74404>. + +=back + +=head1 Testing + +=over 4 + +=item * + +The new F<t/lib/universal.t> script tests the Internal::* functions and other +things in F<universal.c>. + +=item * + +A rare race condition in F<t/op/while_readdir.t> has been fixed, stopping it +from failing randomly when running tests in parallel. + +=item * + +The new F<t/op/leaky-magic.t> script tests that magic applied to variables in +the main packages does not affect other packages. + +=back + +=head1 Platform Support + +=head2 Platform-Specific Notes + +=over 4 + +=item VMS + +=over 4 + +=item * + +Make C<PerlIOUnix_open> honour default permissions on VMS. + +When C<perlio> became the default and C<unixio> became the default bottom layer, +the most common path for creating files from Perl became C<PerlIOUnix_open>, +which has always explicitly used C<0666> as the permission mask. + +To avoid this, C<0777> is now passed as the permissions to C<open()>. In the +VMS CRTL, C<0777> has a special meaning over and above intersecting with the +current umask; specifically, it allows Unix syscalls to preserve native default +permissions. + +=back + +=back + +=head1 Internal Changes + +=over 4 + +=item * + +C<CALL_FPTR> and C<CPERLscope> have been deprecated. + +Those are left from an old implementation of C<MULTIPLICITY> using C++ objects, +which was removed in Perl 5.8. Nowadays these macros do exactly nothing, so +they shouldn't be used anymore. + +For compatibility, they are still defined for external C<XS> code. Only +extensions defining C<PERL_CORE> must be updated now. + +=item * + +C<lex_stuff_pvs()> has been added as a convenience macro wrapping +C<lex_stuff_pvn()> for literal strings. + +=item * + +The recursive part of the peephole optimizer is now hookable. + +In addition to C<PL_peepp>, for hooking into the toplevel peephole optimizer, a +C<PL_rpeepp> is now available to hook into the optimizer recursing into +side-chains of the optree. + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +A regression introduced in Perl 5.12.0, making +C<< my $x = 3; $x = length(undef) >> result in C<$x> set to C<3> has been +fixed. C<$x> will now be C<undef>. + +=item * + +A fatal error in regular expressions when processing UTF-8 data has been fixed +L<[perl #75680]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75680>. + +=item * + +An erroneous regular expression engine optimization that caused regex verbs like +C<*COMMIT> to sometimes be ignored has been removed. + +=item * + +The Perl debugger now also works in taint mode +L<[perl #76872]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=76872>. + +=item * + +Several memory leaks in cloning and freeing threaded Perl interpreters have been +fixed L<[perl #77352]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77352>. + +=item * + +A possible string corruption when doing regular expression matches on overloaded +objects has been fixed +L<[perl #77084]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77084>. + +=item * + +Magic applied to variables in the main package no longer affects other packages. +See L</Magic variables outside the main package> above +L<[perl #76138]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=76138>. + +=item * + +Opening a glob reference via C<< open $fh, "E<gt>", \*glob >> will no longer +cause the glob to be corrupted when the filehandle is printed to. This would +cause perl to crash whenever the glob's contents were accessed +L<[perl #77492]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77492>. + +=item * + +The postincrement and postdecrement operators, C<++> and C<-->, used to cause +leaks when being used on references. This has now been fixed. + +=item * + +A bug when replacing the glob of a loop variable within the loop has been fixed +L<[perl #21469]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=21469>. This +means the following code will no longer crash: + + for $x (...) { + *x = *y; + } + +=item * + +Perl would segfault if the undocumented C<Internals> functions that used +reference prototypes were called with the C<&foo()> syntax, e.g. +C<&Internals::SvREADONLY(undef)> +L<[perl #77776]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77776>. + +These functions now call C<SvROK> on their arguments before dereferencing them +with C<SvRV>, and we test for this case in F<t/lib/universal.t>. + +=item * + +When assigning a list with duplicated keys to a hash, the assignment used to +return garbage and/or freed values: + + @a = %h = (list with some duplicate keys); + +This has now been fixed +L<[perl #31865]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=31865>. + +=item * + +An earlier release of the 5.13 series of Perl changed the semantics of opening a +reference to a copy of a glob: + + my $var = *STDOUT; + open my $fh, '>', \$var; + +This was a mistake, and the previous behaviour from Perl 5.10 and 5.12, which is +to treat \$var as a scalar reference, has now been restored. + +=item * + +The regular expression bracketed character class C<[\8\9]> was effectively the +same as C<[89\000]>, incorrectly matching a NULL character. It also gave +incorrect warnings that the C<8> and C<9> were ignored. Now C<[\8\9]> is the +same as C<[89]> and gives legitimate warnings that C<\8> and C<\9> are +unrecognized escape sequences, passed-through. + +=item * + +C<warn()> and C<die()> now respect utf8-encoded scalars +L<[perl #45549]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=45549>. + +=back + +=head1 Known Problems + +=over 4 + +=item * + +The upgrade to Encode-2.40 has caused some tests in the libwww-perl distribution +on CPAN to fail. (Specifically, F<base/message-charset.t> tests 33-36 in version +5.836 of that distribution now fail.) + +=item * + +The upgrade to ExtUtils-MakeMaker-6.57_05 has caused some tests in the +Module-Install distribution on CPAN to fail. (Specifically, F<02_mymeta.t> tests +5 and 21, F<18_all_from.t> tests 6 and 15, F<19_authors.t> tests 5, 13, 21 and +29, and F<20_authors_with_special_characters.t> tests 6, 15 and 23 in version +1.00 of that distribution now fail.) + +=back + +=head1 Acknowledgements + +Perl 5.13.5 represents approximately one month of development since +Perl 5.13.4 and contains 74558 lines of changes across 549 files +from 45 authors and committers: + +Abigail, Alexander Alekseev, Aristotle Pagaltzis, Ben Morrow, Bram, brian d foy, +Chas. Owens, Chris 'BinGOs' Williams, Craig A. Berry, Curtis Jewell, Dagfinn +Ilmari MannsÃ¥ker, David Golden, David Leadbeater, David Mitchell, Eric Brine, +Father Chrysostomos, Florian Ragwitz, Gisle Aas, Jan Dubois, Jerry D. Hedden, +Jesse Vincent, Jim Cromie, Jirka HruÅ¡ka, Karl Williamson, Michael G. Schwern, +Nicholas Clark, Paul Johnson, Philippe Bruhat (BooK), Piotr Fusik, Rafael +Garcia-Suarez, Rainer Tammer, Reini Urban, Ricardo Signes, Rob Hoelz, Robin +Barker, Steffen Mueller, Steve Hay, Steve Peters, Todd Rinaldo, Tony Cook, +Vincent Pit, Yves Orton, Zefram, Zsbán Ambrus, Ævar Arnfjörð Bjarmason. + +Many of the changes included in this version originated in the CPAN +modules included in Perl's core. We're grateful to the entire CPAN +community for helping Perl to flourish. + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5136delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5136delta.pod new file mode 100644 index 00000000000..f8122572897 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5136delta.pod @@ -0,0 +1,799 @@ +=encoding utf8 + +=head1 NAME + +perl5136delta - what is new for perl v5.13.6 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.5 release and +the 5.13.6 release. + +If you are upgrading from an earlier release such as 5.13.4, first read +L<perl5135delta>, which describes differences between 5.13.4 and +5.13.5. + +=head1 Core Enhancements + +=head2 C<(?^...)> regex construct added to signify default modifiers + +A caret (also called a "circumflex accent") C<"^"> immediately following +a C<"(?"> in a regular expression now means that the subexpression is to +not inherit the surrounding modifiers such as C</i>, but to revert to the +Perl defaults. Any modifiers following the caret override the defaults. + +The stringification of regular expressions now uses this +notation. E.g., before, C<qr/hlagh/i> would be stringified as +C<(?i-xsm:hlagh)>, but now it's stringified as C<(?^i:hlagh)>. + +The main purpose of this is to allow tests that rely on the +stringification to not have to change when new modifiers are added. +See L<perlre/Extended Patterns>. + +=head2 C<"d">, C<"l">, and C<"u"> regex modifiers added + +These modifiers are currently only available within a C<(?...)> construct. + +The C<"l"> modifier says to compile the regular expression as if it were +in the scope of C<use locale>, even if it is not. + +The C<"u"> modifier says to compile the regular expression as if it were +in the scope of a C<use feature "unicode_strings"> pragma. + +The C<"d"> modifier is used to override any C<use locale> and +C<use feature "unicode_strings"> pragmas that are in effect at the time +of compiling the regular expression. + +See just below and L<perlre/(?dlupimsx-imsx)>. + +=head2 C<use feature "unicode_strings"> now applies to some regex matching + +Another chunk of the L<perlunicode/The "Unicode Bug"> is fixed in this +release. Now, regular expressions compiled within the scope of the +"unicode_strings" feature will match the same whether or not the target +string is encoded in utf8, with regard to C<\s>, C<\w>, C<\b>, and their +complements. Work is underway to add the C<[[:posix:]]> character +classes and case sensitive matching to the control of this feature, but +was not complete in time for this dot release. + +=head2 C<\N{...}> now handles Unicode named character sequences + +Unicode has a number of named character sequences, in which particular sequences +of code points are given names. C<\N{...}> now recognizes these. +See L<charnames>. + +=head2 New function C<charnames::string_vianame()> + +This function is a run-time version of C<\N{...}>, returning the string +of characters whose Unicode name is its parameter. It can handle +Unicode named character sequences, whereas the pre-existing +C<charnames::vianame()> cannot, as the latter returns a single code +point. +See L<charnames>. + +=head2 Reentrant regular expression engine + +It is now safe to use regular expressions within C<(?{...})> and +C<(??{...})> code blocks inside regular expressions. + +These block are still experimental, however, and still have problems with +lexical (C<my>) variables, lexical pragmata and abnormal exiting. + +=head2 Custom per-subroutine check hooks + +XS code in an extension module can now annotate a subroutine (whether +implemented in XS or in Perl) so that nominated XS code will be called +at compile time (specifically as part of op checking) to change the op +tree of that subroutine. The compile-time check function (supplied by +the extension module) can implement argument processing that can't be +expressed as a prototype, generate customised compile-time warnings, +perform constant folding for a pure function, inline a subroutine +consisting of sufficiently simple ops, replace the whole call with a +custom op, and so on. This was previously all possible by hooking the +C<entersub> op checker, but the new mechanism makes it easy to tie the +hook to a specific subroutine. See L<perlapi/cv_set_call_checker>. + +To help in writing custom check hooks, several subtasks within standard +C<entersub> op checking have been separated out and exposed in the API. + +=head2 Return value of C<delete $+{...}> + +Custom regular expression engines can now determine the return value of +C<delete> on an entry of C<%+> or C<%->. + +=head2 C<keys>, C<values> work on arrays + +You can now use the C<keys>, C<values>, C<each> builtin functions on arrays +(previously you could only use them on hashes). See L<perlfunc> for details. +This is actually a change introduced in perl 5.12.0, but it was missed from +that release's perldelta. + +=head1 Incompatible Changes + +=head2 Stringification of regexes has changed + +Default regular expression modifiers are now notated by using +C<(?^...)>. Code relying on the old stringification will fail. The +purpose of this is so that when new modifiers are added, such code will +not have to change (after this one time), as the stringification will +automatically incorporate the new modifiers. + +Code that needs to work properly with both old- and new-style regexes +can avoid the whole issue by using (for Perls since 5.9.5): + + use re qw(regexp_pattern); + my ($pat, $mods) = regexp_pattern($re_ref); + +where C<$re_ref> is a reference to a compiled regular expression. Upon +return, C<$mods> will be a string containing all the non-default +modifiers used when the regular expression was compiled, and C<$pattern> +the actual pattern. + +If the actual stringification is important, or older Perls need to be +supported, you can use something like the following: + + # Accept both old and new-style stringification + my $modifiers = (qr/foobar/ =~ /\Q(?^/) ? '^' : '-xism'; + +And then use C<$modifiers> instead of C<-xism>. + +=head2 Regular expressions retain their localeness when interpolated + +Regular expressions compiled under C<"use locale"> now retain this when +interpolated into a new regular expression compiled outside a +C<"use locale">, and vice-versa. + +Previously, a regular expression interpolated into another one inherited +the localeness of the surrounding one, losing whatever state it +originally had. This is considered a bug fix, but may trip up code that +has come to rely on the incorrect behavior. + +=head2 Directory handles not copied to threads + +On systems that do not have a C<fchdir> function, newly-created threads no +longer inherit directory handles from their parent threads. Such programs +would probably have crashed anyway +L<[perl #75154]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75154>. + +=head2 Negation treats strings differently from before + +The unary negation operator C<-> now treats strings that look like numbers +as numbers +L<[perl #57706]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=57706>. + +=head2 Negative zero + +Negative zero (-0.0), when converted to a string, now becomes "0" on all +platforms. It used to become "-0" on some, but "0" on others. + +If you still need to determine whether a zero is negative, use +C<sprintf("%g", $zero) =~ /^-/> or the L<Data::Float> module on CPAN. + +=head1 Performance Enhancements + +=over 4 + +=item * + +The bulk of the C<Tie::Hash::NamedCapture> module used to be in the perl +core. It has now been moved to an XS module, to reduce the overhead for +programs that do not use C<%+> or C<%->. + +=item * + +Eliminate C<PL_*> accessor functions under ithreads. + +When C<MULTIPLICITY> was first developed, and interpreter state moved into an +interpreter struct, thread and interpreter local C<PL_*> variables were defined +as macros that called accessor functions, returning the address of the value, +outside of the perl core. The intent was to allow members within the interpreter +struct to change size without breaking binary compatibility, so that bug fixes +could be merged to a maintenance branch that necessitated such a size change. + +However, some non-core code defines C<PERL_CORE>, sometimes intentionally to +bypass this mechanism for speed reasons, sometimes for other reasons but with +the inadvertent side effect of bypassing this mechanism. As some of this code is +widespread in production use, the result is that the core B<can't> change the +size of members of the interpreter struct, as it will break such modules +compiled against a previous release on that maintenance branch. The upshot is +that this mechanism is redundant, and well-behaved code is penalised by +it. Hence it can and should be removed. + +=back + +=head1 Modules and Pragmata + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +C<Archive::Extract> has been upgraded from version 0.42 to 0.44 + +=item * + +C<Carp> has been upgraded from version 1.18 to 1.19. + +It no longer autovivifies the C<*CORE::GLOBAL::caller> glob, something it +started doing in 1.18, which was released with perl 5.13.4 +L<[perl #78082]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=78082> + +=item * + +C<Compress::Raw::Bzip2> has been upgraded from version 2.030 to 2.031 + +Updated to use bzip2 1.0.6 + +=item * + +C<CPAN> has been upgraded from version 1.94_57 to 1.94_61 + +=item * + +C<Data::Dumper> has been upgraded from version 2.128 to 2.129. + +C<Dumpxs> no longer crashes with globs returned by C<*$io_ref> +L<[perl #72332]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=72332>. + +=item * + +C<Digest::MD5> has been upgraded from version 2.40 to 2.51. + +It is now safe to use this module in combination with threads. + +=item * + +C<File::DosGlob> has been upgraded from version 1.02 to 1.03. + +It allows patterns containing literal parentheses (they no longer need to +be escaped). On Windows, it no longer adds an extra F<./> to the file names +returned when the pattern is a relative glob with a drive specification, +like F<c:*.pl> +L<[perl #71712]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=71712>. + +=item * + +C<File::Find> has been upgraded from version 1.17 to 1.18. + +It improves handling of backslashes on Windows, so that paths such as +F<c:\dir\/file> are no longer generated +L<[perl #71710]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=71710>. + +=item * + +C<if> has been upgraded from version 0.05 to 0.06 + +=item * + +C<IPC::Cmd> has been upgraded from version 0.60 to 0.64 + +=item * + +C<IPC::Open3> has been upgraded from version 1.06 to 1.07. + +The internal C<xclose> routine now knows how to handle file descriptors, as +documented, so duplicating STDIN in a child process using its file +descriptor now works +L<[perl #76474]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=71710>. + +=item * + +C<Locale::Codes> has been upgraded from version 3.13 to 3.14. + +=item * + +C<Locale::Maketext> has been upgraded from version 1.15 to 1.16. + +It fixes an infinite loop in C<Locale::Maketext::Guts::_compile()> when +working with tainted values +(L<CPAN RT #40727|https://rt.cpan.org/Public/Bug/Display.html?id=40727>). + +C<< ->maketext >> calls will now backup and restore C<$@> so that error +messages are not suppressed +(L<CPAN RT #34182|https://rt.cpan.org/Public/Bug/Display.html?id=34182>). + +=item * + +C<Math::BigInt> has been upgraded from version 1.95 to 1.97. + +This prevents C<sqrt($int)> from crashing under C<use bigrat;> +L<[perl #73534]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=73534>. + +=item * + +C<NEXT> has been upgraded from version 0.64 to 0.65. + +=item * + +C<overload> has been upgraded from version 1.10 to 1.11. + +C<overload::Method> can now handle subroutines that are themselves blessed +into overloaded classes +L<[perl #71998]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=71998>. + +=item * + +C<PathTools> has been upgraded from version 3.31_01 to 3.34. + +=item * + +C<podlators> has been upgraded from version 2.3.1 to 2.4.0 + +=item * + +C<sigtrap> has been upgraded from version 1.04 to 1.05. + +It no longer tries to modify read-only arguments when generating a +backtrace +L<[perl #72340]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=72340>. + +=item * + +C<threads> has been upgraded from version 1.77_03 to 1.81_01. + +=item * + +C<threads::shared> has been upgrade from version 1.33_03 to 1.34 + +=item * + +C<Unicode::Collate> has been upgraded from version 0.59 to 0.63 + +U::C::Locale newly supports locales: ar, be, bg, de__phonebook, hu, hy, kk, mk, nso, om, +tn, vi, hr, ig, ru, sq, se, sr, to and uk + +=item * + +C<Unicode::Normalize> has been upgraded from version 1.06 to 1.07 + +=item * + +C<B::Deparse> has been upgraded from version 0.98 to 0.99 + +B::Deparse now properly handles the code that applies a conditional +pattern match against implicit C<$_> as it was fixed in +L<[perl #20444]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=20444>. + +=item * + +C<GDBM_File> has been upgraded from version 1.10 to 1.11 + +=back + +=head1 Documentation + +=head2 Changes to Existing Documentation + +=head3 L<perlapi> + +=over 4 + +=item * + +The documentation for the C<SvTRUE> macro was simply wrong in stating that +get-magic is not processed. It has been corrected. + +=back + +=head1 Diagnostics + +The following additions or changes have been made to diagnostic output, +including warnings and fatal error messages. For the complete list of +diagnostic messages, see L<perldiag>. + +=head2 Changes to Existing Diagnostics + +=over 4 + +=item * + +The 'Layer does not match this perl' error message has been replaced with +these more helpful messages: + +=over 4 + +=item * + +PerlIO layer function table size (%d) does not match size expected by this +perl (%d) + +=item * + +PerlIO layer instance size (%d) does not match size expected by this perl +(%d) + +=back + +L<[perl #73754]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=73754> + +=back + +=head1 Testing + +=over 4 + +=item * + +The script F<t/op/threads-dirh.t> has been added, which tests interaction +of threads and directory handles. + +=back + +=head1 Platform Support + +=head2 Platform-Specific Notes + +=over 4 + +=item IRIX + +Conversion of strings to floating-point numbers is now more accurate on +IRIX systems +L<[perl #32380]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=32380>. + +=item Mac OS X + +Early versions of Mac OS X (Darwin) had buggy implementations of the +C<setregid>, C<setreuid>, C<setrgid> and C<setruid> functions, so perl +would pretend they did not exist. + +These functions are now recognised on Mac OS 10.5 (Leopard; Darwin 9) and +higher, as they have been fixed +L<[perl #72990]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=72990>. + +=item OpenVOS + +perl now builds again with OpenVOS (formerly known as Stratus VOS) +L<[perl #78132]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=78132>. + +=item VMS + +The shortening of symbols longer than 31 characters in the C sources is +now done by the compiler rather than by xsubpp (which could only do so +for generated symbols in XS code). + +=item Windows + +C<$Config{gccversion}> is now set correctly when perl is built using the +mingw64 compiler from L<http://mingw64.org> +L<[perl #73754]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=73754>. + +The build process proceeds more smoothly with mingw and dmake when +F<C:\MSYS\bin> is in the PATH, due to a C<Cwd> fix. + +=back + +=head1 Internal Changes + +=over 4 + +=item * + +See L</Regular expressions retain their localeness when interpolated>, +above. + +=item * + +The C<sv_cmp_flags>, C<sv_cmp_locale_flags>, C<sv_eq_flags> and +C<sv_collxfrm_flags> functions have been added. These are like their +non-_flags counterparts, but allow one to specify whether get-magic is +processed. + +The C<sv_cmp>, C<sv_cmp_locale>, C<sv_eq> and C<sv_collxfrm> functions have +been replaced with wrappers around the new functions. + +=item * + +A new C<sv_2bool_flags> function has been added. + +This is like C<sv_2bool>, but it lets the calling code decide whether +get-magic is handled. C<sv_2bool> is now a macro that calls the new +function. + +=item * + +A new macro, C<SvTRUE_nomg>, has been added. + +This is like C<SvTRUE>, except that it does not process magic. It uses the +new C<sv_2bool_flags> function. + +=item * + +C<sv_catsv_flags> no longer calls C<mg_get> on its second argument (the +source string) if the flags passed to it do not include SV_GMAGIC. So it +now matches the documentation. + +=item * + +A new interface has been added for custom check hooks on subroutines. See +L</Custom per-subroutine check hooks>, above. + +=item * + +List op building functions have been added to the +API. See L<op_append_elem|perlapi/op_append_elem>, +L<op_append_list|perlapi/op_append_list>, and +L<op_prepend_elem|perlapi/op_prepend_elem>. + +=item * + +The L<LINKLIST|perlapi/LINKLIST> macro, part of op building that +constructs the execution-order op chain, has been added to the API. + +=item * + +Many functions ending with pvn now have equivalent pv/pvs/sv versions. + +=item * + +The C<save_freeop>, C<save_op>, C<save_pushi32ptr> and C<save_pushptrptr> +functions have been added to the API. + +=item * + +The new API function C<parse_stmtseq()> parses a sequence of statements, up +to closing brace or EOF. + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +A regular expression match in the right-hand side of a global substitution +(C<s///g>) that is in the same scope will no longer cause match variables +to have the wrong values on subsequent iterations. This can happen when an +array or hash subscript is interpolated in the right-hand side, as in +C<s|(.)|@a{ print($1), /./ }|g> +L<[perl #19078]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=19078>. + +=item * + +Constant-folding used to cause + + $text =~ ( 1 ? /phoo/ : /bear/) + +to turn into + + $text =~ /phoo/ + +at compile time. Now it correctly matches against C<$_> +L<[perl #20444]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=20444>. + +=item * + +Parsing Perl code (either with string C<eval> or by loading modules) from +within a C<UNITCHECK> block no longer causes the interpreter to crash +L<[perl #70614]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=70614>. + +=item * + +When C<-d> is used on the shebang (C<#!>) line, the debugger now has access +to the lines of the main program. In the past, this sometimes worked and +sometimes did not, depending on what order things happened to be arranged +in memory +L<[perl #71806]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=71806>. + +=item * + +The C<y///> or C<tr///> operator now calls get-magic (e.g., the C<FETCH> +method of a tie) on its left-hand side just once, not twice +L<[perl #76814]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=76814>. + +=item * + +String comparison (C<eq>, C<ne>, C<lt>, C<gt>, C<le>, C<ge> and +C<cmp>) and logical not (C<not> and C<!>) operators no longer call magic +(e.g., tie methods) twice on their operands +L<[perl #76814]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=76814>. + +This bug was introduced in an earlier 5.13 release, and does not affect +perl 5.12. + +=item * + +When a tied (or other magic) variable is used as, or in, a regular +expression, it no longer has its C<FETCH> method called twice +L<[perl #76814]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=76814>. + +This bug was introduced in an earlier 5.13 release, and does not affect +perl 5.12. + +=item * + +The C<-C> command line option can now be followed by other options +L<[perl #72434]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=72434>. + +=item * + +Assigning a glob to a PVLV used to convert it to a plain string. Now it +works correctly, and a PVLV can hold a glob. This would happen when a +nonexistent hash or array element was passed to a subroutine: + + sub { $_[0] = *foo }->($hash{key}); + # $_[0] would have been the string "*main::foo" + +It also happened when a glob was assigned to, or returned from, an element +of a tied array or hash +L<[perl #36051]|http://rt.perl.org/rt3//Public/Bug/Display.html?id=36051>. + +=item * + +Creating a new thread when directory handles were open used to cause a +crash, because the handles were not cloned, but simply passed to the new +thread, resulting in a double free. + +Now directory handles are cloned properly, on systems that have a C<fchdir> +function. On other systems, new threads simply do not inherit directory +handles from their parent threads +L<[perl #75154]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75154>. + +=item * + +The regular expression parser no longer hangs when parsing C<\18> and +C<\88>. + +This bug was introduced in version 5.13.5 and did not affect earlier +versions +L<[perl #78058]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78058>. + +=item * + +Subroutine redefinition works once more in the debugger +L<[perl #48332]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=48332>. + +=item * + +The C<&> C<|> C<^> bitwise operators no longer coerce read-only arguments +L<[perl #20661]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=20661>. + +=item * + +Stringifying a scalar containing -0.0 no longer has the affect of turning +false into true +L<[perl #45133]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=45133>. + +=item * + +Aliasing packages by assigning to globs or deleting packages by deleting +their containing stash elements used to have erratic effects on method +resolution, because the internal 'isa' caches were not reset. This has been +fixed. + +=item * + +C<sort> with a custom sort routine could crash if too many nested +subroutine calls occurred from within the sort routine +L<[perl #77930]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77930>. + +This bug was introduced in an earlier 5.13 release, and did not affect +perl 5.12. + +=item * + +The C<eval_sv> and C<eval_pv> C functions now set C<$@> correctly when +there is a syntax error and no C<G_KEEPERR> flag, and never set it if the +C<G_KEEPERR> flag is present +L<[perl #3719]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=3719>. + +=item * + +Nested C<map> and C<grep> blocks no longer leak memory when processing +large lists +L<[perl #48004]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=48004>. + +=item * + +Malformed C<version> objects no longer cause crashes +L<[perl #78286]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78286>. + +=item * + +The interpreter no longer crashes when freeing deeply-nested arrays of +arrays. Hashes have not been fixed yet +L<[perl #44225]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=44225>. + +=item * + +The mechanism for freeing objects in globs used to leave dangling +pointers to freed SVs, meaning Perl users could see corrupted state +during destruction. + +Perl now only frees the affected slots of the GV, rather than freeing +the GV itself. This makes sure that there are no dangling refs or +corrupted state during destruction. + +=item * + +The typeglob C<*,>, which holds the scalar variable C<$,> (output field +separator), had the wrong reference count in child threads. + +=item * + +C<splice> now calls set-magic. This means that, for instance, changes made +by C<splice @ISA> are respected by method calls +L<[perl #78400]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78400>. + +=item * + +C<use v5.8> no longer leaks memory +L<[perl #78436]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78436>. + +=item * + +The XS multicall API no longer causes subroutines to lose reference counts +if called via the multicall interface from within those very subroutines. +This affects modules like List::Util. Calling one of its functions with an +active subroutine as the first argument could cause a crash +L<[perl #78070]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78070>. + +=back + +=head1 Errata + +=over 4 + +=item * + +Fixed a typo in L<perl5135delta> regarding array slices and smart matching + +=back + +=head1 Acknowledgements + +Perl 5.13.6 represents approximately one month of development since Perl +5.13.5 and contains 67920 lines of changes across 566 files from 47 authors +and committers: + +A. Sinan Unur, Aaron Crane, Alex Davies, Ali Polatel, Allen Smith, Andrew Rodland, +Andy Dougherty, Ben Morrow, brian d foy, Casey West, Chip Salzenberg, Chris +'BinGOs' Williams, Craig A. Berry, David Golden, David Mitchell, Eric Brine, +Father Chrysostomos, Florian Ragwitz, George Greer, gregor herrmann, Jan Dubois, +Jerry D. Hedden, Jesse Vincent, Joshua Pritikin, Karl Williamson, kmx, Michael +G Schwern, Mike Kelly, Nicholas Clark, Paul Green, Rafael Garcia-Suarez, Renee +Baecker, Ricardo Signes, Sisyphus, Slaven Rezic, Steffen Müller, Steve Hay, +Sullivan Beck, Tatsuhiko Miyagawa, Todd Rinaldo, Tony Cook, Tye McQueen, Vernon +Lyon, Walt Mankowski, Zefram, Zsbán Ambrus, Ævar Arnfjörð Bjarmason. + +Many of the changes included in this version originated in the CPAN +modules included in Perl's core. We're grateful to the entire CPAN +community for helping Perl to flourish. + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5137delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5137delta.pod new file mode 100644 index 00000000000..0a65b4365a9 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5137delta.pod @@ -0,0 +1,945 @@ +=encoding utf8 + +=head1 NAME + +perl5137delta - what is new for perl v5.13.7 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.6 release and +the 5.13.7 release. + +If you are upgrading from an earlier release such as 5.13.5, first read +L<perl5136delta>, which describes differences between 5.13.5 and +5.13.6. + +=head1 Core Enhancements + +=head2 Single term prototype + +The C<+> prototype is a special alternative to C<$> that will act like +C<\[@%]> when given a literal array or hash variable, but will otherwise +force scalar context on the argument. This is useful for functions which +should accept either a literal array or an array reference as the argument: + + sub smartpush (+@) { + my $aref = shift; + die "Not an array or arrayref" unless ref $aref eq 'ARRAY'; + push @$aref, @_; + } + +When using the C<+> prototype, your function must check that the argument +is of an acceptable type. + +=head2 C<use re '/flags';> + +The C<re> pragma now has the ability to turn on regular expression flags +till the end of the lexical scope: + + use re '/x'; + "foo" =~ / (.+) /; # /x implied + +See L<re/"'/flags' mode"> for details. + +=head2 Statement labels can appear in more places + +Statement labels can now occur before any type of statement or declaration, +such as C<package>. + +=head2 C<use feature "unicode_strings"> now applies to more regex matching + +Another chunk of the L<perlunicode/The "Unicode Bug"> is fixed in this +release. Now, regular expressions compiled within the scope of the +"unicode_strings" feature (or under the "u" regex modifier (specifiable +currently only with infix notation C<(?u:...)> or via C<use re '/u'>) +will match the same whether or not the target string is encoded in utf8, +with regard to C<[[:posix:]]> character classes + +Work is underway to add the case sensitive matching to the control of +this feature, but was not complete in time for this dot release. + +=head2 Array and hash container functions accept references + +All built-in functions that operate directly on array or hash +containers now also accept hard references to arrays or hashes: + + |----------------------------+---------------------------| + | Traditional syntax | Terse syntax | + |----------------------------+---------------------------| + | push @$arrayref, @stuff | push $arrayref, @stuff | + | unshift @$arrayref, @stuff | unshift $arrayref, @stuff | + | pop @$arrayref | pop $arrayref | + | shift @$arrayref | shift $arrayref | + | splice @$arrayref, 0, 2 | splice $arrayref, 0, 2 | + | keys %$hashref | keys $hashref | + | keys @$arrayref | keys $arrayref | + | values %$hashref | values $hashref | + | values @$arrayref | values $arrayref | + | ($k,$v) = each %$hashref | ($k,$v) = each $hashref | + | ($k,$v) = each @$arrayref | ($k,$v) = each $arrayref | + |----------------------------+---------------------------| + +This allows these built-in functions to act on long dereferencing chains +or on the return value of subroutines without needing to wrap them in +C<@{}> or C<%{}>: + + push @{$obj->tags}, $new_tag; # old way + push $obj->tags, $new_tag; # new way + + for ( keys %{$hoh->{genres}{artists}} ) {...} # old way + for ( keys $hoh->{genres}{artists} ) {...} # new way + +For C<push>, C<unshift> and C<splice>, the reference will auto-vivify +if it is not defined, just as if it were wrapped with C<@{}>. + +Calling C<keys> or C<values> directly on a reference gives a substantial +performance improvement over explicit dereferencing. + +For C<keys>, C<values>, C<each>, when overloaded dereferencing is +present, the overloaded dereference is used instead of dereferencing the +underlying reftype. Warnings are issued about assumptions made in the +following three ambiguous cases: + + (a) If both %{} and @{} overloading exists, %{} is used + (b) If %{} overloading exists on a blessed arrayref, %{} is used + (c) If @{} overloading exists on a blessed hashref, @{} is used + +=head2 y///r + +The C</r> flag, which was added to C<s///> in 5.13.2, has been extended to +the C<y///> operator. + +It causes it to perform the substitution on a I<copy> of its operand, +returning that copy instead of a character count. + +=head2 New global variable C<${^GLOBAL_PHASE}> + +A new global variable, C<${^GLOBAL_PHASE}>, has been added to allow +introspection of the current phase of the perl interpreter. It's explained in +detail in L<perlvar/"${^GLOBAL_PHASE}"> and +L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">. + +=head2 Unicode Version 6.0 is now supported (mostly) + +Perl comes with the Unicode 6.0 data base updated with +L<Corrigendum #8|http://www.unicode.org/versions/corrigendum8.html>, +with one exception noted below. +See L<http://unicode.org/versions/Unicode6.0.0> for details on the new +release. Perl does not support any Unicode provisional properties, +including the new ones for this release, but their database files are +packaged with Perl. + +Unicode 6.0 has chosen to use the name C<BELL> for the character at U+1F514, +which is a symbol that looks like a bell, and used in Japanese cell +phones. This conflicts with the long-standing Perl usage of having +C<BELL> mean the ASCII C<BEL> character, U+0007. In Perl 5.14, +C<\N{BELL}> will continue to mean U+0007, but its use will generate a +deprecated warning message, unless such warnings are turned off. The +new name for U+0007 in Perl will be C<ALERT>, which corresponds nicely +with the existing shorthand sequence for it, C<"\a">. C<\N{BEL}> will +mean U+0007, with no warning given. The character at U+1F514 will not +have a name in 5.14, but can be referred to by C<\N{U+1F514}>. The plan +is that in Perl 5.16, C<\N{BELL}> will refer to U+1F514, and so all code +that uses C<\N{BELL}> should convert by then to using C<\N{ALERT}>, +C<\N{BEL}>, or C<"\a"> instead. + +=head2 Improved support for custom OPs + +Custom ops can now be registered with the new C<custom_op_register> C +function and the C<XOP> structure. This will make it easier to add new +properties of custom ops in the future. Two new properties have been added +already, C<xop_class> and C<xop_peep>. + +C<xop_class> is one of the OA_*OP constants, and allows L<B> and other +introspection mechanisms to work with custom ops that aren't BASEOPs. +C<xop_peep> is a pointer to a function that will be called for ops of this +type from C<Perl_rpeep>. + +See L<perlguts/Custom Operators> and L<perlapi/Custom Operators> for more +detail. + +The old C<PL_custom_op_names>/C<PL_custom_op_descs> interface is still +supported but discouraged. + +=head1 Incompatible Changes + +=head2 Dereferencing typeglobs + +If you assign a typeglob to a scalar variable: + + $glob = *foo; + +the glob that is copied to C<$glob> is marked with a special flag +indicating that the glob is just a copy. This allows subsequent assignments +to C<$glob> to overwrite the glob. The original glob, however, is +immutable. + +Many Perl operators did not distinguish between these two types of globs. +This would result in strange behaviour in edge cases: C<untie $scalar> +would do nothing if the last thing assigned to the scalar was a glob +(because it treated it as C<untie *$scalar>, which unties a handle). +Assignment to a glob slot (e.g., C<(*$glob) = \@some_array>) would simply +assign C<\@some_array> to C<$glob>. + +To fix this, the C<*{}> operator (including the C<*foo> and C<*$foo> forms) +has been modified to make a new immutable glob if its operand is a glob +copy. Various operators that make a distinction between globs and scalars +have been modified to treat only immutable globs as globs. + +This causes an incompatible change in code that assigns a glob to the +return value of C<*{}> when that operator was passed a glob copy. Take the +following code, for instance: + + $glob = *foo; + *$glob = *bar; + +The C<*$glob> on the second line returns a new immutable glob. That new +glob is made an alias to C<*bar>. Then it is discarded. So the second +assignment has no effect. + +It also means that C<tie $handle> will now tie C<$handle> as a scalar, even +if it has had a glob assigned to it. + +The upside to this incompatible change is that bugs +L<[perl #77496]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77496>, +L<[perl #77502]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77502>, +L<[perl #77508]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77508>, +L<[perl #77688]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77688>, +and +L<[perl #77812]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77812>, +and maybe others, too, have been fixed. + +See L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=77810> for even +more detail. + +=head2 Clearing stashes + +Stash list assignment C<%foo:: = ()> used to make the stash anonymous +temporarily while it was being emptied. Consequently, any of its +subroutines referenced elsewhere would become anonymous (showing up as +"(unknown)" in C<caller>). Now they retain their package names, such that +C<caller> will return the original sub name if there is still a reference +to its typeglob, or "foo::__ANON__" otherwise +L<[perl #79208]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=79208>. + +=head1 Deprecations + +=head2 C<\N{BELL}> is deprecated + +This is because Unicode is using that name for a different character. +See L</Unicode Version 6.0 is now supported (mostly)> for more +explanation. + +=head1 Performance Enhancements + +=over 4 + +=item * + +When an object has many weak references to it, freeing that object +can under some some circumstances take O(N^2) time to free (where N is the +number of references). The number of circumstances has been reduced. +L<[perl #75254]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75254>. + +=back + +=head1 Modules and Pragmata + +=head2 New Modules and Pragmata + +=over 4 + +=item * + +The following modules were added by the C<Unicode::Collate> +upgrade from 0.63 to 0.67. See below for details. + +C<Unicode::Collate::CJK::Big5> + +C<Unicode::Collate::CJK::GB2312> + +C<Unicode::Collate::CJK::JISX0208> + +C<Unicode::Collate::CJK::Korean> + +C<Unicode::Collate::CJK::Pinyin> + +C<Unicode::Collate::CJK::Stroke> + +=back + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +C<Archive::Extract> has been upgraded from 0.44 to 0.46 + +Resolves an issue with NetBSD-current and its new unzip +executable. + +=item * + +C<Archive::Tar> has been upgraded from 1.68 to 1.72 + +This adds the ptargrep utility for using regular expressions against +the contents of files in a tar archive. + +=item * + +C<B> has been upgraded from 1.24 to 1.26. + +It no longer crashes when taking apart a C<y///> containing characters +outside the octet range or compiled in a C<use utf8> scope. + +The size of the shared object has been reduced by about 40%, with no +reduction in functionality. + +=item * + +C<B::Deparse> has been upgraded from 0.99 to 1.01. + +It fixes deparsing of C<our> followed by a variable with funny characters +(as permitted under the C<utf8> pragma) +L<[perl #33752]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=33752>. + +=item * + +C<CGI> has been upgraded from 3.49 to 3.50 + +This provides the following security fixes: the MIME boundary in +multipart_init is now random and improvements to the handling of +newlines embedded in header values. + +The documentation for param_fetch() has been corrected and clarified. + +=item * + +C<CPAN> has been upgraded from 1.94_61 to 1.94_62 + +=item * + +C<CPANPLUS> has been upgraded from 0.9007 to 0.9010 + +Fixes for the SQLite source engine and resolving of issues with the +testsuite when run under local::lib and/or cpanminus + +=item * + +C<CPANPLUS::Dist::Build> has been upgraded from 0.48 to 0.50 + +=item * + +C<Data::Dumper> has been upgraded from 2.129 to 2.130_01. + +=item * + +C<DynaLoader> has been upgraded from 1.10 to 1.11. + +It fixes a buffer overflow when passed a very long file name. + +=item * + +C<ExtUtils::Constant> has been upgraded from 0.22 to 0.23. + +The C<AUTOLOAD> helper code generated by C<ExtUtils::Constant::ProxySubs> +can now C<croak> for missing constants, or generate a complete C<AUTOLOAD> +subroutine in XS, allowing simplification of many modules that use it. +(C<Fcntl>, C<File::Glob>, C<GDBM_File>, C<I18N::Langinfo>, C<POSIX>, C<Socket>) + +C<ExtUtils::Constant::ProxySubs> can now optionally push the names of all +constants onto the package's C{@EXPORT_OK}. This has been used to replace +less space-efficient code in C<B>, helping considerably shrink the size of its +shared object. + +=item * + +C<Fcntl> has been upgraded from 1.09 to 1.10. + +=item * + +C<File::Fetch> has been upgraded from 0.24 to 0.28 + +C<HTTP::Lite> is now supported for 'http' scheme. + +The C<fetch> utility is supported on FreeBSD, NetBSD and +Dragonfly BSD for the C<http> and C<ftp> schemes. + +=item * + +C<File::Glob> has been upgraded from 1.09 to 1.10. + +=item * + +C<File::stat> has been upgraded from 1.03 to 1.04. + +The C<-x> and C<-X> file test operators now work correctly under the root +user. + +=item * + +C<GDBM_File> has been upgraded from 1.11 to 1.12. + +This fixes a memory leak when DBM filters are used. + +=item * + +C<Hash::Util> has been upgraded from 0.09 to 0.10. + +=item * + +C<Hash::Util::FieldHash> has been upgraded from 1.05 to 1.06. + +=item * + +C<I18N::Langinfo> has been upgraded from 0.06 to 0.07. + +=item * + +C<Locale::Maketext> has been upgraded from 1.16 to 1.17. + +=item * + +C<Math::BigInt> has been upgraded from 1.97 to 1.99_01. + +=item * + +C<Math::BigRat> has been upgraded from 0.26 to 0.26_01 + +=item * + +C<Math::BigInt::FastCalc> has been upgraded from 0.22 to 0.24_01. + +=item * + +C<MIME::Base64> has been upgraded from 3.09 to 3.10 + +Includes new functions to calculate the length of encoded and decoded +base64 strings. + +=item * + +C<mro> has been upgraded from 1.04 to 1.05. + +=item * + +C<NDBM_File> has been upgraded from 1.09 to 1.10. + +This fixes a memory leak when DBM filters are used. + +=item * + +C<ODBM_File> has been upgraded from 1.08 to 1.09. + +This fixes a memory leak when DBM filters are used. + +=item * + +C<Opcode> has been upgraded from 1.16 to 1.17. + +=item * + +C<parent> has been upgraded from 0.223 to 0.224 + +=item * + +C<Pod::Simple> has been upgraded from 3.14 to 3.15 + +Includes various fixes to C<HTML> and C<XHTML> handling. + +=item * + +C<POSIX> has been upgraded from 1.21 to 1.22. + +=item * + +C<re> has been upgraded from 0.13 to 0.14, for the sake of the new +C<use re "/flags"> pragma. + +=item * + +C<Safe> has been upgraded from 2.28 to 2.29. + +It adds C<&version::vxs::VCMP> to the default share. + +=item * + +C<SDBM_File> has been upgraded from 1.07 to 1.08. + +=item * + +C<SelfLoader> has been upgraded from 1.17 to 1.18. + +It now works in taint mode +L<[perl #72062]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=72062>. + +=item * + +C<Socket> has been upgraded from 1.90 to 1.91. + +=item * + +C<Storable> has been upgraded from 2.22 to 2.24 + +Includes performance improvement for overloaded classes. + +=item * + +C<Sys::Hostname> has been upgraded from 1.13 to 1.14. + +=item * + +C<Unicode::Collate> has been upgraded from 0.63 to 0.67 + +This release newly adds locales C<ja> C<ko> and C<zh> and its variants +( C<zh__big5han>, C<zh__gb2312han>, C<zh__pinyin>, C<zh__stroke> ). + +Supported UCA_Version 22 for Unicode 6.0.0. + +The following modules have been added: + +C<Unicode::Collate::CJK::Big5> for C<zh__big5han> which makes +tailoring of CJK Unified Ideographs in the order of CLDR's big5han ordering. + +C<Unicode::Collate::CJK::GB2312> for C<zh__gb2312han> which makes +tailoring of CJK Unified Ideographs in the order of CLDR's gb2312han ordering. + +C<Unicode::Collate::CJK::JISX0208> which makes tailoring of 6355 kanji +(CJK Unified Ideographs) in the JIS X 0208 order. + +C<Unicode::Collate::CJK::Korean> which makes tailoring of CJK Unified Ideographs +in the order of CLDR's Korean ordering. + +C<Unicode::Collate::CJK::Pinyin> for C<zh__pinyin> which makes +tailoring of CJK Unified Ideographs in the order of CLDR's pinyin ordering. + +C<Unicode::Collate::CJK::Stroke> for C<zh__stroke> which makes +tailoring of CJK Unified Ideographs in the order of CLDR's stroke ordering. + +=back + +=head1 Documentation + +L<perlvar> reorders the variables and groups them by topic. Each variable +introduced after Perl 5.000 notes the first version in which it is +available. L<perlvar> also has a new section for deprecated variables to +note when they were removed. + +=head2 New Documentation + +=head3 L<perlpodstyle> + +New style guide for POD documentation, +split mostly from the NOTES section of the pod2man man page. + +( This was added to C<v5.13.6> but was not documented with that release ). + +=head2 Changes to Existing Documentation + +=over + +=item * + +Array and hash slices in scalar context are now documented in L<perldata>. + +=item * + +L<perlform> and L<perllocale> have been corrected to state that +C<use locale> affects formats. + +=back + +=head1 Diagnostics + +=head2 New Diagnostics + +=over 4 + +=item * + +"Using !~ with %s doesn't make sense": This message was actually added in +5.13.2, but was omitted from perldelta. It now applies also to the C<y///> +operator, and has been documented. + +=back + +=head1 Utility Changes + +=head3 L<ptargrep> + +=over 4 + +=item * + +L<ptargrep> is a utility to apply pattern matching to the contents of files +in a tar archive. It comes with C<Archive::Tar>. + +=back + +=head1 Testing + +=over 4 + +=item * + +The new F<t/mro/isa_aliases.t> has been added, which tests that +C<*Foo::ISA = *Bar::ISA> works properly. + +=item * + +F<t/mro/isarev.t> has been added, which tests that C<PL_isarev> (accessible +at the Perl level via C<mro::get_isarev>) is updated properly. + +=item * + +F<t/run/switchd-78586.t> has been added, which tests that +L<[perl #78586]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78586> +has been fixed (related to line numbers in the debugger). + +=back + +=head1 Platform Support + +=head2 Platform-Specific Notes + +=over 4 + +=item Windows + +Directory handles are now properly cloned when threads are created. In perl +5.13.6, child threads simply stopped inheriting directory handles. In +previous versions, threads would share handles, resulting in crashes. + +Support for building with Visual C++ 2010 is now underway, but is not yet +complete. See F<README.win32> for more details. + +=item VMS + +Record-oriented files (record format variable or variable with fixed control) +opened for write by the perlio layer will now be line buffered to prevent the +introduction of spurious line breaks whenever the perlio buffer fills up. + +=back + +=head1 Internal Changes + +=over 4 + +=item * + +C<lex_start> has been added to the API, but is considered experimental. + +=item * + +A new C<parse_block> function has been added to the API +L<[perl #78222]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78222>. + +=item * + +A new, experimental API has been added for accessing the internal +structure that Perl uses for C<%^H>. See the functions beginning with +C<cophh_> in L<perlapi>. + +=item * + +A stash can now have a list of effective names in addition to its usual +name. The first effective name can be accessed via the C<HvENAME> macro, +which is now the recommended name to use in MRO linearisations (C<HvNAME> +being a fallback if there is no C<HvENAME>). + +These names are added and deleted via C<hv_ename_add> and +C<hv_ename_delete>. These two functions are I<not> part of the API. + +=item * + +The way the parser handles labels has been cleaned up and refactored. As a +result, the C<newFOROP()> constructor function no longer takes a parameter +stating what label is to go in the state op. + +=item * + +The C<newWHILEOP()> and C<newFOROP()> functions no longer accept a line +number as a parameter. + +=item * + +A new C<parse_barestmt()> function has been added, for parsing a statement +without a label. + +=item * + +A new C<parse_label()> function has been added, that parses a statement +label, separate from statements. + +=item * + +The C<CvSTASH()> macro can now only be used as an rvalue. C<CvSTASH_set()> +has been added to replace assignment to C<CvSTASH()>. This is to ensure +that backreferences are handled properly. These macros are not part of the +API. + +=item * + +The C<op_scope()> and C<op_lvalue()> functions have been added to the API, +but are considered experimental. + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +The C<parse_stmt> C function added in earlier in the 5.13.x series has been +fixed to work with statements ending with C<}> +L<[perl #78222]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78222>. + +=item * + +The C<parse_fullstmt> C function added in 5.13.5 has been fixed to work +when called while an expression is being parsed. + +=item * + +Characters in the Latin-1 non-ASCII range (0x80 to 0xFF) used not to match +themselves if the string happened to be UTF8-encoded internally, the +regular expression was not, and the character in the regular expression was +inside a repeated group (e.g., +C<Encode::decode_utf8("\303\200") =~ /(\xc0)+/>) +L<[perl #78464]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78464>. + +=item * + +The C<(?d)> regular expression construct now overrides a previous C<(?u)> +or C<use feature "unicode_string"> +L<[perl #78508]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78508>. + +=item * + +A memory leak in C<do "file">, introduced in perl 5.13.6, has been fixed +L<[perl #78488]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78488>. + +=item * + +Various bugs related to typeglob dereferencing have been fixed. See +L</Dereferencing typeglobs>, above. + +=item * + +The C<SvPVbyte> function available to XS modules now calls magic before +downgrading the SV, to avoid warnings about wide characters +L<[perl #72398]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=72398>. + +=item * + +The C<=> operator used to ignore magic (e.g., tie methods) on its +right-hand side if the scalar happened to hold a typeglob. This could +happen if a typeglob was the last thing returned from or assigned to a tied +scalar +L<[perl #77498]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77498>. + +=item * + +C<sprintf> was ignoring locales when called with constant arguments +L<[perl #78632]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78632>. + +=item * + +A non-ASCII character in the Latin-1 range could match both a Posix +class, such as C<[[:alnum:]]>, and its inverse C<[[:^alnum:]]>. This is +now fixed for regular expressions compiled under the C<"u"> modifier. +See L</C<use feature "unicode_strings"> now applies to more regex matching>. +L<[perl #18281]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=18281>. + +=item * + +Concatenating long strings under C<use encoding> no longer causes perl to +crash +L<[perl #78674]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78674>. + +=item * + +Typeglob assignments would crash if the glob's stash no longer existed, so +long as the glob assigned to was named 'ISA' or the glob on either side of +the assignment contained a subroutine. + +=item * + +Calling C<< ->import >> on a class lacking an import method could corrupt +the stack, resulting in strange behaviour. For instance, + + push @a, "foo", $b = bar->import; + +would assign 'foo' to C<$b> +L<[perl #63790]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=63790>. + +=item * + +Creating an alias to a package when that package had been detached from the +symbol table would result in corrupted isa caches +L<[perl #77358]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77358>. + +=item * + +C<.=> followed by C<< <> >> or C<readline> would leak memory if C<$/> +contained characters beyond the octet range and the scalar assigned to +happened to be encoded as UTF8 internally +L<[perl #72246]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=72246>. + +=item * + +The C<recv> function could crash when called with the MSG_TRUNC flag +L<[perl #75082]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75082>. + +=item * + +Evaluating a simple glob (like C<*a>) was calling get-magic on the glob, +even when its contents were not being used +L<[perl #78580]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78580>. + +This bug was introduced in 5.13.2 and did not affect earlier perl versions. + +=item * + +Matching a Unicode character against an alternation containing characters +that happened to match continuation bytes in the former's UTF8 +representation (C<qq{\x{30ab}} =~ /\xab|\xa9/>) would cause erroneous +warnings +L<[perl #70998]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=70998>. + +=item * + +C<s///r> (added in 5.13.2) no longer leaks. + +=item * + +The trie optimisation was not taking empty groups into account, preventing +'foo' from matching C</\A(?:(?:)foo|bar|zot)\z/> +L<[perl #78356]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78356>. + +=item * + +A pattern containing a C<+> inside a lookahead would sometimes cause an +incorrect match failure in a global match (e.g., C</(?=(\S+))/g>) +L<[perl #68564]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=68564>. + +=item * + +Iterating with C<foreach> over an array returned by an lvalue sub now works +L<[perl #23790]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=23790>. + +=item * + +C<$@> is now localised during calls to C<binmode> to prevent action at a +distance +L<[perl #78844]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78844>. + +=item * + +C<PL_isarev>, which is accessible to Perl via C<mro::get_isarev> is now +updated properly when packages are deleted or removed from the C<@ISA> of +other classes. This allows many packages to be created and deleted without +causing a memory leak +L<[perl #75176]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75176>. + +=item * + +C<undef *Foo::> and C<undef *Foo::ISA> and C<delete $package::{ISA}> +used not to update the internal isa caches if the +stash or C<@ISA> array had a reference elsewhere. In +fact, C<undef *Foo::ISA> would stop a new C<@Foo::ISA> array from updating +caches. + +=item * + +C<@ISA> arrays can now be shared between classes via +C<*Foo::ISA = \@Bar::ISA> or C<*Foo::ISA = *Bar::ISA> +L<[perl #77238]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77238>. + +=item * + +The parser no longer hangs when encountering certain Unicode characters, +such as U+387 +L<[perl #74022]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=74022>. + +=item * + +C<formline> no longer crashes when passed a tainted format picture. It also +taints C<$^A> now if its arguments are tainted +L<[perl #79138]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=79138>. + +=item * + +A signal handler called within a signal handler could cause leaks or +double-frees. Now fixed. +L<[perl #76248]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=76248>. + +=item * + +When trying to report C<Use of uninitialized value $Foo::BAR>, crashes could +occur if the GLOB of the global variable causing the warning has been detached +from its original stash by, for example C<delete $::{'Foo::'}>. This has been +fixed by disabling the reporting of variable names in the warning in those +cases. + +=back + +=head1 Obituary + +Randy Kobes, creator of the kobesearch alternative to search.cpan.org and +contributor/maintainer to several core Perl toolchain modules, passed away +on September 18, 2010 after a battle with lung cancer. His contributions +to the Perl community will be missed. + +=head1 Acknowledgements + +Perl 5.13.7 represents approximately one month of development since Perl 5.13.6 +and contains 73100 lines of changes across 518 files from 39 authors and committers: + +Abhijit Menon-Sen, Abigail, Ben Morrow, Chas. J. Owens IV, Chris 'BinGOs' Williams, Craig A. Berry, +David Golden, David Mitchell, Father Chrysostomos, Fingle Nark, Florian Ragwitz, George Greer, +Grant McLean, H.Merijn Brand, Ian Goodacre, Jan Dubois, Jerry D. Hedden, Jesse Vincent, Karl Williamson, +Lubomir Rintel, Marty Pauley, Moritz Lenz, Nicholas Clark, Nicolas Kaiser, Niko Tyni, Peter John Acklam, +Rafael Garcia-Suarez, Shlomi Fish, Steffen Mueller, Steve Hay, Tatsuhiko Miyagawa, Tim Bunce, Todd Rinaldo, +Tom Christiansen, Tom Hukins, Tony Cook, Yves Orton, Zefram and brian d foy + +Many of the changes included in this version originated in the CPAN modules included in +Perl's core. We're grateful to the entire CPAN community for helping Perl to flourish. + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5138delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5138delta.pod new file mode 100644 index 00000000000..1b01b2701c1 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5138delta.pod @@ -0,0 +1,912 @@ +=encoding utf8 + +=head1 NAME + +perl5138delta - what is new for perl v5.13.8 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.7 release and +the 5.13.8 release. + +If you are upgrading from an earlier release such as 5.13.6, first read +L<perl5137delta>, which describes differences between 5.13.6 and +5.13.7. + +=head1 Core Enhancements + +=head2 C<-d:-foo> calls C<Devel::foo::unimport> + +The syntax C<-dI<B<:>foo>> was extended in 5.6.1 to make C<-dI<:fooB<=bar>>> +equivalent to C<-MDevel::foo=bar>, which expands +internally to C<use Devel::foo 'bar';>. +F<perl> now allows prefixing the module name with C<->, with the same +semantics as C<-M>, I<i.e.> + +=over 4 + +=item C<-d:-foo> + +Equivalent to C<-M-Devel::foo>, expands to +C<no Devel::foo;>, calls C<< Devel::foo->unimport() >> +if the method exists. + +=item C<-d:-foo=bar> + +Equivalent to C<-M-Devel::foo=bar>, expands to C<no Devel::foo 'bar';>, +calls C<< Devel::foo->unimport('bar') >> if the method exists. + +=back + +This is particularly useful to suppresses the default actions of a +C<Devel::*> module's C<import> method whilst still loading it for debugging. + +=head2 Filehandle method calls load L<IO::File> on demand + +When a method call on a filehandle would die because the method cannot +be resolved, and L<IO::File> has not been loaded, Perl now loads L<IO::File> +via C<require> and attempts method resolution again: + + open my $fh, ">", $file; + $fh->binmode(":raw"); # loads IO::File and succeeds + +This also works for globs like STDOUT, STDERR and STDIN: + + STDOUT->autoflush(1); + +Because this on-demand load only happens if method resolution fails, the +legacy approach of manually loading an L<IO::File> parent class for partial +method support still works as expected: + + use IO::Handle; + open my $fh, ">", $file; + $fh->autoflush(1); # IO::File not loaded + +=head2 Full functionality for C<use feature 'unicode_strings'> + +This release provides full functionality for C<use feature +'unicode_strings'>. Under its scope, all string operations executed and +regular expressions compiled (even if executed outside its scope) have +Unicode semantics. See L<feature>. + +This feature avoids most forms of the "Unicode Bug" (See +L<perlunicode/The "Unicode Bug"> for details.) If there is a +possibility that your code will process Unicode strings, you are +B<strongly> encouraged to use this subpragma to avoid nasty surprises. + +The availability of this should strongly affect the whole tone of +various documents, such as L<perlunicode> and L<perluniintro>, but this +work has not been done yet. + +=head2 Exception Handling Backcompat Hack + +When an exception is thrown in an C<eval BLOCK>, C<$@> is now set before +unwinding, as well as being set after unwinding as the eval block exits. This +early setting supports code that has historically treated C<$@> during unwinding +as an indicator of whether the unwinding was due to an exception. These modules +had been broken by 5.13.1's change from setting C<$@> early to setting it late. +This double setting arrangement is a stopgap until the reason for unwinding can +be made properly introspectable. C<$@> has never been a reliable indicator of +the reason for unwinding. + +=head2 printf-like functions understand post-1980 size modifiers + +Perl's printf and sprintf operators, and Perl's internal printf replacement +function, now understand the C90 size modifiers "hh" (C<char>), "z" +(C<size_t>), and "t" (C<ptrdiff_t>). Also, when compiled with a C99 +compiler, Perl now understands the size modifier "j" (C<intmax_t>). + +So, for example, on any modern machine, C<sprintf('%hhd', 257)> returns '1'. + +=head2 DTrace probes now include package name + +The DTrace probes now include an additional argument (C<arg3>) which contains +the package the subroutine being entered or left was compiled in. + +For example using the following DTrace script: + + perl$target:::sub-entry + { + printf("%s::%s\n", copyinstr(arg0), copyinstr(arg3)); + } + +and then running: + + perl -e'sub test { }; test' + +DTrace will print: + + main::test + +=head2 Stacked labels + +Multiple statement labels can now appear before a single statement. + +=head1 Incompatible Changes + +=head2 C<:=> is now a syntax error + +Previously C<my $pi := 4;> was exactly equivalent to C<my $pi : = 4;>, +with the C<:> being treated as the start of an attribute list, ending before +the C<=>. The use of C<:=> to mean C<: => was deprecated in 5.12.0, and is now +a syntax error. This will allow the future use of C<:=> as a new token. + +We find no Perl 5 code on CPAN using this construction, outside the core's +tests for it, so we believe that this change will have very little impact on +real-world codebases. + +If it is absolutely necessary to have empty attribute lists (for example, +because of a code generator) then avoid the error by adding a space before +the C<=>. + +=head2 Run-time code block in regular expressions + +Code blocks in regular expressions (C<(?{...})> and C<(??{...})>) used not +to inherit any pragmata (strict, warnings, etc.) if the regular expression +was compiled at run time as happens in cases like these two: + + use re 'eval'; + $foo =~ $bar; # when $bar contains (?{...}) + $foo =~ /$bar(?{ $finished = 1 })/; + +This was a bug, which has now been fixed. But it has the potential to break +any code that was relying on this bug. + +=head1 Deprecations + +=head2 C<?PATTERN?> is deprecated + +C<?PATTERN?> (without the initial m) has been deprecated and now produces +a warning. This is to allow future use of C<?> in new operators. +The match-once functionality is still available in the form of C<m?PATTERN?>. + +=head2 C<sv_compile_2op()> is now deprecated + +The C<sv_compile_2op()> API function is now deprecated. Searches suggest +that nothing on CPAN is using it, so this should have zero impact. + +It attempted to provide an API to compile code down to an optree, but failed +to bind correctly to lexicals in the enclosing scope. It's not possible to +fix this problem within the constraints of its parameters and return value. + +=head2 Tie functions on scalars holding typeglobs + +Calling a tie function (C<tie>, C<tied>, C<untie>) with a scalar argument +acts on a file handle if the scalar happens to hold a typeglob. + +This is a long-standing bug that will be removed in Perl 5.16, as +there is currently no way to tie the scalar itself when it holds +a typeglob, and no way to untie a scalar that has had a typeglob +assigned to it. + +This bug was fixed in 5.13.7 but, because of the breakage it caused, the +fix has been reverted. Now there is a deprecation warning whenever a tie +function is used on a handle without an explicit C<*>. + +=head1 Modules and Pragmata + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +C<Archive::Tar> has been upgraded from version 1.72 to 1.74. + +Skip extracting pax extended headers. + +=item * + +C<autodie> has been upgraded from version 2.10 to 2.1001. + +Test fix in blead for VMS. + +=item * + +C<B> has been upgraded from version 1.26 to 1.27. + +Avoid compiler warnings. + +=item * + +C<B::Concise> has been upgraded from version 0.81 to 0.82. + +It no longer produces mangled output with the C<-tree> option +L<[perl #80632]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=80632>. + +=item * + +C<B::Deparse> has been upgraded from version 1.01 to 1.02. + +Test improvements. + +=item * + +C<Cwd> has been upgraded from version 3.34 to 3.35. + +Avoid compiler warnings. + +=item * + +C<Data::Dumper> has been upgraded from version 2.130_01 to 2.130_02. + +Avoid compiler warnings. + +=item * + +C<Devel::Peek> has been upgraded from version 1.05 to 1.06. + +Avoid compiler warnings. + +Test improvements. + +=item * + +C<Devel::SelfStubber> has been upgraded from version 1.03 to 1.05. + +Whitespace changes. + +=item * + +C<Digest::SHA> has been upgraded from 5.48 to 5.50. + +C<shasum> now more closely mimics C<sha1sum>/C<md5sum>. + +C<Addfile> accepts all POSIX filenames. + +=item * + +C<Dumpvalue> has been upgraded from version 1.14 to 1.15. + +Test improvements. + +=item * + +C<DynaLoader> has been upgraded from version 1.11 to 1.12. + +Remove obsolete RCS keywords. + +=item * + +C<Env> has been upgraded from version 1.01 to 1.02. + +Test improvements. + +=item * + +C<ExtUtils::CBuilder> has been upgraded from 0.2703 to 0.280201. + +Handle C and C++ compilers separately. + +Preserves exit status on VMS. + +Test improvements. + +=item * + +C<ExtUtils::Constant::Utils> has been upgraded from 0.02 to 0.03. + +Refactoring and fixing of backcompat code, preparing for resynchronisation +with CPAN. + +=item * + +C<ExtUtils::Embed> has been upgraded from 1.29 to 1.30. + +Remove obsolete RCS keywords. + +=item * + +C<ExtUtils::ParseXS> has been upgraded from 2.2207 to 2.2208. + +Avoid compiler warnings. + +=item * + +C<Fcntl> has been upgraded from 1.10 to 1.11. + +Avoid compiler warnings. + +Test improvements. + +=item * + +C<feature> has been upgraded from 1.18 to 1.19. + +Documentation and test updates for the C<unicode_strings> feature. +See L</Full functionality for C<use feature 'unicode_strings'>>. + +=item * + +C<File::CheckTree> has been upgraded from 4.4 to 4.41. + +Whitespace changes. + +=item * + +C<File::Glob> has been upgraded from 1.10 to 1.11. + +Avoid compiler warnings. + +Test improvements. + +=item * + +C<GDBM_File> has been upgraded from 1.12 to 1.13. + +Test improvements. + +Remove obsolete RCS keywords. + +=item * + +C<Hash::Util::FieldHash> has been upgraded from 1.06 to 1.07. + +Avoid compiler warnings. + +=item * + +C<I18N::Collate> has been upgraded from 1.01 to 1.02. + +Whitespace changes. + +Test improvements. + +=item * + +C<if> has been upgraded from 0.06 to 0.0601. + +Test improvements. + +=item * + +C<IO> has been upgraded from 1.25_02 to 1.25_03. + +Avoid compiler warnings. + +=item * + +C<IPC::Cmd> has been upgraded from 0.64 to 0.66. + +Resolves an issue with splitting Win32 command lines. + +Documentation enhancements. + +=item * + +C<IPC::Open3> has been upgraded from 1.07 to 1.08. + +Remove obsolete RCS keywords. + +Test improvements. + +=item * + +C<Locale::Codes> has been upgraded from version 3.14 to 3.15. + +Adds some codes. + +=item * + +C<Math::BigInt> has been upgraded from 1.99_01 to 1.99_02. + +Documentation and comment spelling fixes. + +=item * + +C<Memoize> has been upgraded from version 1.01_03 to 1.02. + +Remove obsolete RCS keywords. + +Whitespace changes. + +=item * + +C<MIME::Base64> has been upgraded from 3.10 to 3.13. + +Now provides C<encode_base64url> and C<decode_base64url> functions to process +the base64 scheme for "URL applications". + +=item * + +C<mro> has been upgraded from version 1.05 to 1.06. + +C<next::method> I<et al.> now take into account that every class inherits +from UNIVERSAL +L<[perl #68654]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=68654>. + +=item * + +C<NDBM_File> has been upgraded from 1.10 to 1.11. + +Remove obsolete RCS keywords. + +Test improvements. + +=item * + +C<Net::Ping> has been upgraded from 2.36 to 2.37. + +Remove obsolete RCS keywords. + +=item * + +C<ODBM_File> has been upgraded from 1.09 to 1.10. + +Remove obsolete RCS keywords. + +Test improvements. + +=item * + +C<Opcode> has been upgraded from 1.17 to 1.18. + +Avoid compiler warnings. + +Test improvements. + +=item * + +C<overload> has been upgraded from 1.11 to 1.12. + +Avoid a taint problem in use of sprintf. + +Test asymmetric fallback cases +L<[perl #71286]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=71286>. + +=item * + +C<PerlIO::encoding> has been upgraded from 0.13 to 0.14. + +Avoid compiler warnings. + +Remove obsolete RCS keywords. + +Test improvements. + +=item * + +C<PerlIO::scalar> has been upgraded from 0.10 to 0.11. + +A C<read> after a C<seek> beyond the end of the string no longer thinks it +has data to read +L<[perl #78716]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78716>. + +Avoid compiler warnings. + +=item * + +C<PerlIO::via> has been upgraded from 0.10 to 0.11. + +Avoid compiler warnings. + +=item * + +C<POSIX> has been upgraded from 1.22 to 1.23. + +Avoid compiler warnings. + +=item * + +C<re> has been upgraded from 0.14 to 0.15. + +Enforce that C</d>, C</u>, and C</l> are mutually exclusive. + +=item * + +C<SDBM_File> has been upgraded from 1.08 to 1.09. + +Avoid compiler warnings. + +Remove obsolete RCS keywords. + +Test improvements. + +=item * + +C<Socket> has been upgraded from 1.91 to 1.92. + +It has several new functions for handling IPv6 addresses. + +=item * + +C<Storable> has been upgraded from 2.24 to 2.25. + +This adds support for serialising code references that contain UTF-8 strings +correctly. The Storable minor version number changed as a result, meaning that +Storable users who set C<$Storable::accept_future_minor> to a C<FALSE> value +will see errors (see L<Storable/FORWARD COMPATIBILITY> for more details). + +Freezing no longer gets confused if the Perl stack gets reallocated +during freezing +L<[perl #80074]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=80074>. + +Avoid compiler warnings. + +=item * + +C<threads> has been upgraded from 1.81_02 to 1.81_03. + +Avoid compiler warnings. + +=item * + +C<threads::shared> has been upgraded from 1.34 to 1.35. + +Avoid compiler warnings. + +=item * + +C<Time::HiRes> has been upgraded from 1.9721 to 1.9721_01. + +Build fix in blead for VMS. + +=item * + +C<Unicode::Collate> has been upgraded from 0.67 to 0.6801. + +Documentation clarification. + +Test improvements. + +=item * + +C<Unicode::Normalize> has been upgraded from 1.07 to 1.08. + +Avoid compiler warnings. + +=item * + +C<Unicode::UCD> has been upgraded from 0.29 to 0.30. + +Add info about named sequence alternatives. + +Don't use C<CompositionExclusions.txt>. + +=item * + +C<version> has been upgraded from 0.82 to 0.86. + +Modify export logic for C<is_strict> and C<is_lax>. + +Various backcompat fixes. + +=item * + +C<Win32> has been upgraded from 0.39 to 0.41. + +Add several functions. + +Corrections to names returned by C<Win32::GetOSName> and +C<Win32::GetOSDisplayName>. + +=item * + +C<XS::APItest> has been upgraded from 0.26 to 0.27. + +Test new API functions. + +Avoid compiler warnings. + +=back + +=head2 Dual-life Modules and Pragmata + +These modules were formerly distributed only in the Perl core +distribution, and are now dual-lifed (meaning they are now also available +separately on CPAN): + +=over 4 + +=item * + +C<autouse> + +=item * + +C<Devel::SelfStubber> + +=item * + +C<Dumpvalue> + +=item * + +C<Env> + +=item * + +C<File::CheckTree> + +=item * + +C<I18N::Collate> + +=back + +=head1 Diagnostics + +The following additions or changes have been made to diagnostic output, +including warnings and fatal error messages. For the complete list of +diagnostic messages, see L<perldiag>. + +=head2 New Diagnostics + +=over 4 + +=item * + +There is a new "Closure prototype called" error +L<[perl #68560]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=68560>. + +=back + +=head2 Changes to Existing Diagnostics + +=over 4 + +=item * + +The "Found = in conditional" warning that is emitted when a constant is +assigned to a variable in a condition is now withheld if the constant is +actually a subroutine or one generated by C<use constant>, since the value +of the constant may not be known at the time the program is written +L<[perl #77762]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77762>. + +=back + +=head1 Configuration and Compilation + +=over 4 + +=item * + +The C<Encode> module can now (once again) be included in a static Perl +build. The special-case handling for this situation got broken in Perl +5.11.0, and has now been repaired. + +=back + +=head1 Testing + +=over 4 + +=item * + +Tests for C<Fcntl>, C<File::Glob>, C<GDBM_File>, C<IPC::Open3>, +C<NDBM_File>, C<ODBM_File>, C<Opcode>, C<PerlIO::encoding>, C<SDBM_File>, +and C<Storable> now use the L<Test::More> framework. + +=back + +=head1 Platform Support + +=head2 Platform-Specific Notes + +=over 4 + +=item NetBSD + +The NetBSD hints file has been changed to make the system's malloc the +default. + +=item Windows + +The option to use an externally-supplied C<crypt()>, or to build with no +C<crypt()> at all, has been removed. Perl supplies its own C<crypt()> +implementation for Windows, and the political situation that required +this part of the distribution to sometimes be omitted is long gone. + +=back + +=head1 Internal Changes + +=over 4 + +=item * + +The L<C<mg_findext()>|perlapi/mg_findext> and +L<C<sv_unmagicext()>|perlapi/sv_unmagicext> +functions have been added to the API. +They allow extension authors to find and remove magic attached to +scalars based on both the magic type and the magic virtual table, similar to how +C<sv_magicext()> attaches magic of a certain type and with a given virtual table +to a scalar. This eliminates the need for extensions to walk the list of +C<MAGIC> pointers of an C<SV> to find the magic that belongs to them. + +=item * + +The +L<C<parse_fullexpr()>|perlapi/parse_fullexpr>, +L<C<parse_listexpr()>|perlapi/parse_listexpr>, +L<C<parse_termexpr()>|perlapi/parse_termexpr>, and +L<C<parse_arithexpr()>|perlapi/parse_arithexpr> +functions have been added to the API. They perform +recursive-descent parsing of expressions at various precedence levels. +They are expected to be used by syntax plugins. + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +C<BEGIN {require 5.12.0}> now behaves as documented, rather than behaving +identically to C<use 5.12.0;>. Previously, C<require> in a C<BEGIN> block +was erroneously executing the C<use feature ':5.12.0'> and +C<use strict; use warnings;> behaviour, which only C<use> was documented to +provide +L<[perl #69050]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=69050>. + +=item * + +C<use 5.42> +L<[perl #69050]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=69050>, +C<use 6> and C<no 5> no longer leak memory. + +=item * + +C<eval "BEGIN{die}"> no longer leaks memory on non-threaded builds. + +=item * + +PerlIO no longer crashes when called recursively, e.g., from a signal +handler. Now it just leaks memory +L<[perl #75556]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=75556>. + +=item * + +Defining a constant with the same name as one of perl's special blocks +(e.g., INIT) stopped working in 5.12.0, but has now been fixed +L<[perl #78634]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=78634>. + +=item * + +A reference to a literal value used as a hash key (C<$hash{\"foo"}>) used +to be stringified, even if the hash was tied +L<[perl #79178]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=79178>. + +=item * + +A closure containing an C<if> statement followed by a constant or variable +is no longer treated as a constant +L<[perl #63540]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=63540>. + +=item * + +Calling a closure prototype (what is passed to an attribute handler for a +closure) now results in a "Closure prototype called" error message instead +of a crash +L<[perl #68560]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=68560>. + +=item * + +A regular expression optimisation would sometimes cause a match with a +C<{n,m}> quantifier to fail when it should match +L<[perl #79152]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=79152>. + +=item * + +What has become known as the "Unicode Bug" is mostly resolved in this release. +Under C<use feature 'unicode_strings'>, the internal storage format of a +string no longer affects the external semantics. There are two known +exceptions. User-defined case changing functions, which are planned to +be deprecated in 5.14, require utf8-encoded strings to function; and the +character C<LATIN SMALL LETTER SHARP S> in regular expression +case-insensitive matching has a somewhat different set of bugs depending +on the internal storage format. Case-insensitive matching of all +characters that have multi-character matches, as this one does, is +problematical in Perl. +L<[perl #58182]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=58182>. + +=item * + +Mentioning a read-only lexical variable from the enclosing scope in a +string C<eval> no longer causes the variable to become writable +L<[perl #19135]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=19135>. + +=item * + +C<state> can now be used with attributes. It used to mean the same thing as +C<my> if attributes were present +L<[perl #68658]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=68658>. + +=item * + +Expressions like C<< @$a > 3 >> no longer cause C<$a> to be mentioned in +the "Use of uninitialized value in numeric gt" warning when C<$a> is +undefined (since it is not part of the C<E<gt>> expression, but the operand +of the C<@>) +L<[perl #72090]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=72090>. + +=item * + +C<require> no longer causes C<caller> to return the wrong file name for +the scope that called C<require> and other scopes higher up that had the +same file name +L<[perl #68712]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=68712>. + +=item * + +The ref types in the typemap for XS bindings now support magical variables +L<[perl #72684]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=72684>. + +=item * + +Match variables (e.g., C<$1>) no longer persist between calls to a sort +subroutine +L<[perl #76026]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=76026>. + +=item * + +The C<B> module was returning C<B::OP>s instead of C<B::LOGOP>s for C<entertry> +L<[perl #80622]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=80622>. +This was due to a bug in the perl core, not in C<B> itself. + +=item * + +Some numeric operators were converting integers to floating point, +resulting in loss of precision on 64-bit platforms +L<[perl #77456]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=77456>. + +=item * + +The fallback behaviour of overloading on binary operators was asymmetric +L<[perl #71286]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=71286>. + +=back + +=head1 Acknowledgements + +Perl 5.13.8 represents approximately one month of development since +Perl 5.13.7 and contains 38715 lines of changes across 546 files from +38 authors and committers. + +Thank you to the following for contributing to this release: + +Abhijit Menon-Sen, Abigail, Andreas KE<0xf6>nig, Ben Morrow, Brad Gilbert, +brian d foy, Chip Salzenberg, Chris 'BinGOs' Williams, Craig A. Berry, +David Golden, David Leadbeater, David Mitchell, Father Chrysostomos, +Florian Ragwitz, Goro Fuji, H.Merijn Brand, Jan Dubois, Jerry D. Hedden, +Jesse Vincent, John Peacock, Karl Williamson, Lukas Mai, Marvin Humphrey, +Max Maischein, Michael Breen, Michael Fig, Nicholas Clark, Nick Cleaton, +Paul Evans, Peter J. Holzer, Peter John Acklam, Rafael Garcia-Suarez, +Reini Urban, Renee Baecker, Ricardo Signes, Tony Cook, Yves Orton, Zefram + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the L<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5139delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5139delta.pod new file mode 100644 index 00000000000..fb9bf36784b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5139delta.pod @@ -0,0 +1,646 @@ +=encoding utf8 + +=head1 NAME + +perl5139delta - what is new for perl v5.13.9 + +=head1 DESCRIPTION + +This document describes differences between the 5.13.8 release and +the 5.13.9 release. + +If you are upgrading from an earlier release such as 5.13.7, first read +L<perl5138delta>, which describes differences between 5.13.7 and +5.13.8. + +=head1 Core Enhancements + +=head2 New regular expression modifier C</a> + +The C</a> regular expression modifier restricts C<\s> to match precisely +the five characters C<[ \f\n\r\t]>, C<\d> to match precisely the 10 +characters C<[0-9]>, C<\w> to match precisely the 63 characters +C<[A-Za-z0-9_]>, and the Posix (C<[[:posix:]]>) character classes to +match only the appropriate ASCII characters. The complements, of +course, match everything but; and C<\b> and C<\B> are correspondingly +affected. Otherwise, C</a> behaves like the C</u> modifier, in that +case-insensitive matching uses Unicode semantics; for example, "k" will +match the Unicode C<\N{KELVIN SIGN}> under C</i> matching, and code +points in the Latin1 range, above ASCII will have Unicode semantics when +it comes to case-insensitive matching. Like its cousins (C</u>, C</l>, +and C</d>), and in spite of the terminology, C</a> in 5.14 will not +actually be able to be used as a suffix at the end of a regular +expression (this restriction is planned to be lifted in 5.16). It must +occur either as an infix modifier, such as C<(?a:...)> or (C<(?a)...>, +or it can be turned on within the lexical scope of C<use re '/a'>. +Turning on C</a> turns off the other "character set" modifiers. + +=head2 Any unsigned value can be encoded as a character + +With this release, Perl is adopting a model that any unsigned value can +be treated as a code point and encoded internally (as utf8) without +warnings -- not just the code points that are legal in Unicode. +However, unless utf8 warnings have been +explicitly lexically turned off, outputting or performing a +Unicode-defined operation (such as upper-casing) on such a code point +will generate a warning. Attempting to input these using strict rules +(such as with the C<:encoding('UTF-8')> layer) will continue to fail. +Prior to this release the handling was very inconsistent, and incorrect +in places. Also, the Unicode non-characters, some of which previously were +erroneously considered illegal in places by Perl, contrary to the Unicode +standard, are now always legal internally. But inputting or outputting +them will work the same as for the non-legal Unicode code points, as the +Unicode standard says they are illegal for "open interchange". + +=head2 Regular expression debugging output improvement + +Regular expression debugging output (turned on by C<use re 'debug';>) now +uses hexadecimal when escaping non-ASCII characters, instead of octal. + +=head1 Security + +=head2 Restrict \p{IsUserDefined} to In\w+ and Is\w+ + +In L<perlunicode/"User-Defined Character Properties">, it says you can +create custom properties by defining subroutines whose names begin with +"In" or "Is". However, perl doesn't actually enforce that naming +restriction, so \p{foo::bar} will call foo::Bar() if it exists. + +This commit finally enforces this convention. Note that this broke a +number of existing tests for properties, since they didn't always use an +Is/In prefix. + +=head1 Incompatible Changes + +=head2 All objects are destroyed + +It used to be possible to prevent a destructor from being called during +global destruction by artificially increasing the reference count of an +object. + +Now such objects I<will> will be destroyed, as a result of a bug fix +L<[perl #81230]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=81230>. + +This has the potential to break some XS modules. (In fact, it break some. +See L</Known Problems>, below.) + +=head1 Modules and Pragmata + +=head2 New Modules and Pragmata + +=over 4 + +=item * + +C<CPAN::Meta::YAML> 0.003 has been added as a dual-life module. It supports a +subset of YAML sufficient for reading and writing META.yml and MYMETA.yml files +included with CPAN distributions or generated by the module installation +toolchain. It should not be used for any other general YAML parsing or +generation task. + +=item * + +C<HTTP::Tiny> 0.009 has been added as a dual-life module. It is a very +small, simple HTTP/1.1 client designed for simple GET requests and file +mirroring. It has has been added to enable CPAN.pm and CPANPLUS to +"bootstrap" HTTP access to CPAN using pure Perl without relying on external +binaries like F<curl> or F<wget>. + +=item * + +C<JSON::PP> 2.27103 has been added as a dual-life module, for the sake of +reading F<META.json> files in CPAN distributions. + +=item * + +C<Module::Metadata> 1.000003 has been added as a dual-life module. It gathers +package and POD information from Perl module files. It is a standalone module +based on Module::Build::ModuleInfo for use by other module installation +toolchain components. Module::Build::ModuleInfo has been deprecated in +favor of this module instead. + +=item * + +C<Perl::OSType> 1.002 has been added as a dual-life module. It maps Perl +operating system names (e.g. 'dragonfly' or 'MSWin32') to more generic types +with standardized names (e.g. "Unix" or "Windows"). It has been refactored +out of Module::Build and ExtUtils::CBuilder and consolidates such mappings into +a single location for easier maintenance. + +=back + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +C<Archive::Extract> has been upgraded from version 0.46 to 0.48 + +=item * + +C<Archive::Tar> has been upgraded from version 1.74 to 1.76 + +=item * + +C<CGI> has been upgraded from version 3.50 to 3.51 + +Further improvements have been made to guard against newline injections +in headers. + +=item * + +C<Compress::Raw::Bzip2> has been upgraded from version 2.031 to 2.033 + +=item * + +C<Compress::Raw::Zlib> has been upgraded from version 2.030 to 2.033 + +=item * + +C<CPAN> has been upgraded from version 1.94_62 to 1.94_63 + +=item * + +C<CPANPLUS> has been upgraded from version 0.9010 to 0.9011 + +=item * + +C<CPANPLUS::Dist::Build> has been upgraded from version 0.50 to 0.52 + +=item * + +C<DB_File> has been upgraded from version 1.820 to 1.821 + +=item * + +C<Encode> has been upgraded from version 2.40 to 2.42. +Now, all 66 Unicode non-characters are treated the same way U+FFFF has +always been treated; if it was disallowed, all 66 are disallowed; if it +warned, all 66 warn. + +=item * + +C<File::Fetch> has been upgraded from version 0.28 to 0.32 + +=item * + +C<IO::Compress> has been upgraded from version 2.030 to 2.033 + +=item * + +C<IPC::Cmd> has been upgraded from version 0.66 to 0.68 + +=item * + +C<Log::Message> has been upgraded from version 0.02 to 0.04 + +=item * + +C<Log::Message::Simple> has been upgraded from version 0.06 to 0.08 + +=item * + +C<Module::Load::Conditional> has been upgraded from version 0.38 to 0.40 + +=item * + +C<Object::Accessor> has been upgraded from version 0.36 to 0.38 + +=item * + +C<Params::Check> has been upgraded from version 0.26 to 0.28 + +=item * + +C<Pod::LaTeX> has been upgraded from version 0.58 to 0.59 + +=item * + +C<Socket> has been updated with new affordances for IPv6, +including implementations of the C<Socket::getaddrinfo()> and +C<Socket::getnameinfo()> functions, along with related constants. + +=item * + +C<Term::UI> has been upgraded from version 0.20 to 0.24 + +=item * + +C<Thread::Queue> has been upgraded from version 2.11 to 2.12. + +=item * + +C<Thread::Semaphore> has been upgraded from version 2.11 to 2.12. + +=item * + +C<threads> has been upgraded from version 1.81_03 to 1.82 + +=item * + +C<threads::shared> has been upgraded from version 1.35 to 1.36 + +=item * + +C<Time::Local> has been upgraded from version 1.1901_01 to 1.2000. + +=item * + +C<Unicode::Normalize> has been upgraded from version 1.07 to 1.10 + +=item * + +C<version> has been upgraded from 0.86 to 0.88. + +=item * + +C<Win32> has been upgraded from version 0.41 to 0.44. + +=back + +=head1 Documentation + +=head2 Changes to Existing Documentation + +=head3 All documentation + +=over + +=item * + +Numerous POD warnings were fixed. + +=item * + +Many, many spelling errors and typographical mistakes were corrected throughout Perl's core. + +=back + +=head3 C<perlhack> + +=over 4 + +=item * + +C<perlhack> was extensively reorganized. + +=back + +=head3 C<perlfunc> + +=over 4 + +=item * + +It has now been documented that C<ord> returns 0 for an empty string. + +=back + +=head1 Diagnostics + +The following additions or changes have been made to diagnostic output, +including warnings and fatal error messages. For the complete list of +diagnostic messages, see L<perldiag>. + +=head2 New Diagnostics + +=over 4 + +=item * + +Performing an operation requiring Unicode semantics (such as case-folding) +on a Unicode surrogate or a non-Unicode character now triggers a warning: +'Operation "%s" returns its argument for ...'. + +=back + +=head2 Changes to Existing Diagnostics + +=over 4 + +=item * + +Previously, if none of the C<gethostbyaddr>, C<gethostbyname> and +C<gethostent> functions were implemented on a given platform, they would +all die with the message 'Unsupported socket function "gethostent" called', +with analogous messages for C<getnet*> and C<getserv*>. This has been +corrected. + +=back + +=head1 Utility Changes + +=head3 C<perlbug> + +=over 4 + +=item * + +C<perlbug> did not previously generate a From: header, potentially +resulting in dropped mail. Now it does include that header. + +=back + +=head3 C<buildtoc> + +=over 4 + +=item * + +F<pod/buildtoc> has been modernized and can now be used to test the +well-formedness of F<pod/perltoc.pod> automatically. + +=back + +=head1 Testing + +=over 4 + +=item * + +C<lib/File/DosGlob.t> has been modernized and now uses C<Test::More>. + +=item * + +A new test script, C<t/porting/filenames.t>, makes sure that filenames and +paths are reasonably portable. + +=item * + +C<t/porting/diag.t> is now several orders of magnitude faster. + +=item * + +C<t/porting/buildtoc.t> now tests that the documentation TOC file is current and well-formed. + +=item * + +C<t/base/while.t> now tests the basics of a while loop with minimal dependencies. + +=item * + +C<t/cmd/while.t> now uses F<test.pl> for better maintainability. + +=item * + +C<t/op/split.t> now tests calls to C<split> without any pattern specified. + +=back + + + +=head1 Platform Support + +=head2 Discontinued Platforms + +=over 4 + +=item Apollo DomainOS + +The last vestiges of support for this platform have been excised from the +Perl distribution. It was officially discontinued in version 5.12.0. It had +not worked for years before that. + +=item MacOS Classic + +The last vestiges of support for this platform have been excised from the +Perl distribution. It was officially discontinued in an earlier version. + +=back + +=head2 Platform-Specific Notes + +=over 4 + + +=item Cygwin + +=over + +=item * + +Updated MakeMaker to build man pages on cygwin. + +=item * + +Improved rebase behaviour + +If a dll is updated on cygwin reuse the old imagebase address. +This solves most rebase errors, esp when updating on core dll's. +See L<http://www.tishler.net/jason/software/rebase/rebase-2.4.2.README> for more information. + +=item * + +Support the standard cyg dll prefix, which is e.g. needed for FFI's. + +=item * + +Updated build hints file + +=back + + +=item Solaris + +DTrace is now supported on Solaris. There used to be build failures, but +these have been fixed +L<[perl #73630]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=73630>. + +=back + +=head1 Internal Changes + +=over 4 + +=item * + +The opcode bodies for C<chop> and C<chomp> and for C<schop> and C<schomp> have +been merged. The implementation functions C<Perl_do_chop()> and +C<Perl_do_chomp()>, never part of the public API, have been merged and moved to +a static function in F<pp.c>. This shrinks the perl binary slightly, and should +not affect any code outside the core (unless it is relying on the order of side +effects when C<chomp> is passed a I<list> of values). + +=item * + +Some of the flags parameters to the uvuni_to_utf8_flags() and +utf8n_to_uvuni() have changed. This is a result of Perl now allowing +internal storage and manipulation of code points that are problematic +in some situations. Hence, the default actions for these functions has +been complemented to allow these code points. The new flags are +documented in L<perlapi>. Code that requires the problematic code +points to be rejected needs to change to use these flags. Some flag +names are retained for backward source compatibility, though they do +nothing, as they are now the default. However the flags +C<UNICODE_ALLOW_FDD0>, C<UNICODE_ALLOW_FFFF>, C<UNICODE_ILLEGAL>, and +C<UNICODE_IS_ILLEGAL> have been removed, as they stem from a +fundamentally broken model of how the Unicode non-character code points +should be handled, which is now described in +L<perlunicode/Non-character code points>. See also L</Selected Bug Fixes>. + +=item * + +Certain shared flags in the C<pmop.op_pmflags> and C<regexp.extflags> +structures have been removed. These are: C<Rxf_Pmf_LOCALE>, +C<Rxf_Pmf_UNICODE>, and C<PMf_LOCALE>. Instead there are encodes and +three static in-line functions for accessing the information: +C<get_regex_charset()>, C<set_regex_charset()>, and C<get_regex_charset_name()>, +which are defined in the places where the original flags were. + +=item * + +A new option has been added to C<pv_escape> to dump all characters above +ASCII in hexadecimal. Before, one could get all characters as hexadecimal +or the Latin1 non-ASCII as octal + + +=item * + +Generate pp_* prototypes in pp_proto.h, and remove pp.sym + +Eliminate the #define pp_foo Perl_pp_foo(pTHX) macros, and update the 13 +locations that relied on them. + +regen/opcode.pl now generates prototypes for the PP functions directly, into +pp_proto.h. It no longer writes pp.sym, and regen/embed.pl no longer reads +this, removing the only ordering dependency in the regen scripts. opcode.pl +is now responsible for prototypes for pp_* functions. (embed.pl remains +responsible for ck_* functions, reading from regen/opcodes) + +=back + +=head1 Selected Bug Fixes + +=over 4 + +=item * + +The handling of Unicode non-characters has changed. +Previously they were mostly considered illegal, except that only one of +the 66 of them was known about in places. The Unicode standard +considers them legal, but forbids the "open interchange" of them. +This is part of the change to allow the internal use of any code point +(see L</Core Enhancements>). Together, these changes resolve +L<# 38722|https://rt.perl.org/rt3/Ticket/Display.html?id=38722>, +L<# 51918|http://rt.perl.org/rt3/Ticket/Display.html?id=51918>, +L<# 51936|http://rt.perl.org/rt3/Ticket/Display.html?id=51936>, +L<# 63446|http://rt.perl.org/rt3/Ticket/Display.html?id=63446> + +=item * + +Sometimes magic (ties, tainted, etc.) attached to variables could cause an +object to last longer than it should, or cause a crash if a tied variable +were freed from within a tie method. These have been fixed +L<[perl #81230]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=81230>. + +=item * + +Most I/O functions were not warning for unopened handles unless the +'closed' and 'unopened' warnings categories were both enabled. Now only +C<use warnings 'unopened'> is necessary to trigger these warnings (as was +always meant to be the case. + +=item * + +C<< E<lt>exprE<gt> >> always respects overloading now if the expression is +overloaded. + +Due to the way that 'E<lt>E<gt> as glob' was parsed differently from +'E<lt>E<gt> as filehandle' from 5.6 onwards, something like C<< E<lt>$foo[0]E<gt> >> did +not handle overloading, even if C<$foo[0]> was an overloaded object. This +was contrary to the documentation for overload, and meant that C<< E<lt>E<gt> >> +could not be used as a general overloaded iterator operator. + +=item * + +Destructors on objects were not called during global destruction on objects +that were not referenced by any scalars. This could happen if an array +element were blessed (e.g., C<bless \$a[0]>) or if a closure referenced a +blessed variable (C<bless \my @a; sub foo { @a }>). + +Now there is an extra pass during global destruction to fire destructors on +any objects that might be left after the usual passes that check for +objects referenced by scalars +L<[perl #36347]|http://rt.perl.org/rt3/Public/Bug/Display.html?id=36347>. + +=item * + +A long standing bug has now been fully fixed (partial fixes came in +earlier releases), in which some Latin-1 non-ASCII characters on +ASCII-platforms would match both a character class and its complement, +such as U+00E2 being both in C<\w> and C<\W>, depending on the +UTF-8-ness of the regular expression pattern and target string. +Fixing this did expose some bugs in various modules and tests that +relied on the previous behavior of C<[[:alpha:]]> not ever matching +U+00FF, "LATIN SMALL LETTER Y WITH DIAERESIS", even when it should, in +Unicode mode; now it does match when appropriate. +L<[perl #60156]|http://rt.perl.org/rt3/Ticket/Display.html?id=60156>. + +=back + +=head1 Known Problems + +=over 4 + +=item * + +The fix for [perl #81230] causes test failures for C<Tk> version 804.029. +This is still being investigated. + +=back + +=head1 Acknowledgements + +Perl 5.13.9 represents approximately one month of development since +Perl 5.13.8 and contains approximately 48000 lines of changes across +809 files from 35 authors and committers: + +Abigail, Ævar Arnfjörð Bjarmason, brian d foy, Chris 'BinGOs' Williams, +Craig A. Berry, David Golden, David Leadbeater, David Mitchell, Father +Chrysostomos, Florian Ragwitz, Gerard Goossen, H.Merijn Brand, Jan +Dubois, Jerry D. Hedden, Jesse Vincent, John Peacock, Karl Williamson, +Leon Timmermans, Michael Parker, Michael Stevens, Nicholas Clark, +Nuno Carvalho, Paul "LeoNerd" Evans, Peter J. Acklam, Peter Martini, +Rainer Tammer, Reini Urban, Renee Baecker, Ricardo Signes, Robin Barker, +Tony Cook, Vadim Konovalov, Vincent Pit, Zefram, and Zsbán Ambrus. + +Many of the changes included in this version originated in the CPAN +modules included in Perl's core. We're grateful to the entire CPAN +community for helping Perl to flourish. + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the L<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5140delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5140delta.pod new file mode 100644 index 00000000000..145d08d463f --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5140delta.pod @@ -0,0 +1,4590 @@ +=encoding utf8 + +=head1 NAME + +perl5140delta - what is new for perl v5.14.0 + +=head1 DESCRIPTION + +This document describes differences between the 5.12.0 release and +the 5.14.0 release. + +If you are upgrading from an earlier release such as 5.10.0, first read +L<perl5120delta>, which describes differences between 5.10.0 and +5.12.0. + +Some of the bug fixes in this release have been backported to subsequent +releases of 5.12.x. Those are indicated with the 5.12.x version in +parentheses. + +=head1 Notice + +As described in L<perlpolicy>, the release of Perl 5.14.0 marks the +official end of support for Perl 5.10. Users of Perl 5.10 or earlier +should consider upgrading to a more recent release of Perl. + +=head1 Core Enhancements + +=head2 Unicode + +=head3 Unicode Version 6.0 is now supported (mostly) + +Perl comes with the Unicode 6.0 data base updated with +L<Corrigendum #8|http://www.unicode.org/versions/corrigendum8.html>, +with one exception noted below. +See L<http://unicode.org/versions/Unicode6.0.0/> for details on the new +release. Perl does not support any Unicode provisional properties, +including the new ones for this release. + +Unicode 6.0 has chosen to use the name C<BELL> for the character at U+1F514, +which is a symbol that looks like a bell, and is used in Japanese cell +phones. This conflicts with the long-standing Perl usage of having +C<BELL> mean the ASCII C<BEL> character, U+0007. In Perl 5.14, +C<\N{BELL}> continues to mean U+0007, but its use generates a +deprecation warning message unless such warnings are turned off. The +new name for U+0007 in Perl is C<ALERT>, which corresponds nicely +with the existing shorthand sequence for it, C<"\a">. C<\N{BEL}> +means U+0007, with no warning given. The character at U+1F514 has no +name in 5.14, but can be referred to by C<\N{U+1F514}>. +In Perl 5.16, C<\N{BELL}> will refer to U+1F514; all code +that uses C<\N{BELL}> should be converted to use C<\N{ALERT}>, +C<\N{BEL}>, or C<"\a"> before upgrading. + +=head3 Full functionality for C<use feature 'unicode_strings'> + +This release provides full functionality for C<use feature +'unicode_strings'>. Under its scope, all string operations executed and +regular expressions compiled (even if executed outside its scope) have +Unicode semantics. See L<feature/"the 'unicode_strings' feature">. +However, see L</Inverted bracketed character classes and multi-character folds>, +below. + +This feature avoids most forms of the "Unicode Bug" (see +L<perlunicode/The "Unicode Bug"> for details). If there is any +possibility that your code will process Unicode strings, you are +I<strongly> encouraged to use this subpragma to avoid nasty surprises. + +=head3 C<\N{I<NAME>}> and C<charnames> enhancements + +=over + +=item * + +C<\N{I<NAME>}> and C<charnames::vianame> now know about the abbreviated +character names listed by Unicode, such as NBSP, SHY, LRO, ZWJ, etc.; all +customary abbreviations for the C0 and C1 control characters (such as +ACK, BEL, CAN, etc.); and a few new variants of some C1 full names that +are in common usage. + +=item * + +Unicode has several I<named character sequences>, in which particular sequences +of code points are given names. C<\N{I<NAME>}> now recognizes these. + +=item * + +C<\N{I<NAME>}>, C<charnames::vianame>, and C<charnames::viacode> +now know about every character in Unicode. In earlier releases of +Perl, they didn't know about the Hangul syllables nor several +CJK (Chinese/Japanese/Korean) characters. + +=item * + +It is now possible to override Perl's abbreviations with your own custom aliases. + +=item * + +You can now create a custom alias of the ordinal of a +character, known by C<\N{I<NAME>}>, C<charnames::vianame()>, and +C<charnames::viacode()>. Previously, aliases had to be to official +Unicode character names. This made it impossible to create an alias for +unnamed code points, such as those reserved for private +use. + +=item * + +The new function charnames::string_vianame() is a run-time version +of C<\N{I<NAME>}}>, returning the string of characters whose Unicode +name is its parameter. It can handle Unicode named character +sequences, whereas the pre-existing charnames::vianame() cannot, +as the latter returns a single code point. + +=back + +See L<charnames> for details on all these changes. + +=head3 New warnings categories for problematic (non-)Unicode code points. + +Three new warnings subcategories of "utf8" have been added. These +allow you to turn off some "utf8" warnings, while allowing +other warnings to remain on. The three categories are: +C<surrogate> when UTF-16 surrogates are encountered; +C<nonchar> when Unicode non-character code points are encountered; +and C<non_unicode> when code points above the legal Unicode +maximum of 0x10FFFF are encountered. + +=head3 Any unsigned value can be encoded as a character + +With this release, Perl is adopting a model that any unsigned value +can be treated as a code point and encoded internally (as utf8) +without warnings, not just the code points that are legal in Unicode. +However, unless utf8 or the corresponding sub-category (see previous +item) of lexical warnings have been explicitly turned off, outputting +or executing a Unicode-defined operation such as upper-casing +on such a code point generates a warning. Attempting to input these +using strict rules (such as with the C<:encoding(UTF-8)> layer) +will continue to fail. Prior to this release, handling was +inconsistent and in places, incorrect. + +Unicode non-characters, some of which previously were erroneously +considered illegal in places by Perl, contrary to the Unicode Standard, +are now always legal internally. Inputting or outputting them +works the same as with the non-legal Unicode code points, because the Unicode +Standard says they are (only) illegal for "open interchange". + +=head3 Unicode database files not installed + +The Unicode database files are no longer installed with Perl. This +doesn't affect any functionality in Perl and saves significant disk +space. If you need these files, you can download them from +L<http://www.unicode.org/Public/zipped/6.0.0/>. + +=head2 Regular Expressions + +=head3 C<(?^...)> construct signifies default modifiers + +An ASCII caret C<"^"> immediately following a C<"(?"> in a regular +expression now means that the subexpression does not inherit surrounding +modifiers such as C</i>, but reverts to the Perl defaults. Any modifiers +following the caret override the defaults. + +Stringification of regular expressions now uses this notation. +For example, C<qr/hlagh/i> would previously be stringified as +C<(?i-xsm:hlagh)>, but now it's stringified as C<(?^i:hlagh)>. + +The main purpose of this change is to allow tests that rely on the +stringification I<not> to have to change whenever new modifiers are added. +See L<perlre/Extended Patterns>. + +This change is likely to break code that compares stringified regular +expressions with fixed strings containing C<?-xism>. + +=head3 C</d>, C</l>, C</u>, and C</a> modifiers + +Four new regular expression modifiers have been added. These are mutually +exclusive: one only can be turned on at a time. + +=over + +=item * + +The C</l> modifier says to compile the regular expression as if it were +in the scope of C<use locale>, even if it is not. + +=item * + +The C</u> modifier says to compile the regular expression as if it were +in the scope of a C<use feature 'unicode_strings'> pragma. + +=item * + +The C</d> (default) modifier is used to override any C<use locale> and +C<use feature 'unicode_strings'> pragmas in effect at the time +of compiling the regular expression. + +=item * + +The C</a> regular expression modifier restricts C<\s>, C<\d> and C<\w> and +the POSIX (C<[[:posix:]]>) character classes to the ASCII range. Their +complements and C<\b> and C<\B> are correspondingly +affected. Otherwise, C</a> behaves like the C</u> modifier, in that +case-insensitive matching uses Unicode semantics. + +If the C</a> modifier is repeated, then additionally in case-insensitive +matching, no ASCII character can match a non-ASCII character. +For example, + + "k" =~ /\N{KELVIN SIGN}/ai + "\xDF" =~ /ss/ai + +match but + + "k" =~ /\N{KELVIN SIGN}/aai + "\xDF" =~ /ss/aai + +do not match. + +=back + +See L<perlre/Modifiers> for more detail. + +=head3 Non-destructive substitution + +The substitution (C<s///>) and transliteration +(C<y///>) operators now support an C</r> option that +copies the input variable, carries out the substitution on +the copy, and returns the result. The original remains unmodified. + + my $old = "cat"; + my $new = $old =~ s/cat/dog/r; + # $old is "cat" and $new is "dog" + +This is particularly useful with C<map>. See L<perlop> for more examples. + +=head3 Re-entrant regular expression engine + +It is now safe to use regular expressions within C<(?{...})> and +C<(??{...})> code blocks inside regular expressions. + +These blocks are still experimental, however, and still have problems with +lexical (C<my>) variables and abnormal exiting. + +=head3 C<use re '/flags'> + +The C<re> pragma now has the ability to turn on regular expression flags +till the end of the lexical scope: + + use re "/x"; + "foo" =~ / (.+) /; # /x implied + +See L<re/"'/flags' mode"> for details. + +=head3 \o{...} for octals + +There is a new octal escape sequence, C<"\o">, in doublequote-like +contexts. This construct allows large octal ordinals beyond the +current max of 0777 to be represented. It also allows you to specify a +character in octal which can safely be concatenated with other regex +snippets and which won't be confused with being a backreference to +a regex capture group. See L<perlre/Capture groups>. + +=head3 Add C<\p{Titlecase}> as a synonym for C<\p{Title}> + +This synonym is added for symmetry with the Unicode property names +C<\p{Uppercase}> and C<\p{Lowercase}>. + +=head3 Regular expression debugging output improvement + +Regular expression debugging output (turned on by C<use re 'debug'>) now +uses hexadecimal when escaping non-ASCII characters, instead of octal. + +=head3 Return value of C<delete $+{...}> + +Custom regular expression engines can now determine the return value of +C<delete> on an entry of C<%+> or C<%->. + +=head2 Syntactical Enhancements + +=head3 Array and hash container functions accept references + +B<Warning:> This feature is considered experimental, as the exact behaviour +may change in a future version of Perl. + +All builtin functions that operate directly on array or hash +containers now also accept unblessed hard references to arrays +or hashes: + + |----------------------------+---------------------------| + | Traditional syntax | Terse syntax | + |----------------------------+---------------------------| + | push @$arrayref, @stuff | push $arrayref, @stuff | + | unshift @$arrayref, @stuff | unshift $arrayref, @stuff | + | pop @$arrayref | pop $arrayref | + | shift @$arrayref | shift $arrayref | + | splice @$arrayref, 0, 2 | splice $arrayref, 0, 2 | + | keys %$hashref | keys $hashref | + | keys @$arrayref | keys $arrayref | + | values %$hashref | values $hashref | + | values @$arrayref | values $arrayref | + | ($k,$v) = each %$hashref | ($k,$v) = each $hashref | + | ($k,$v) = each @$arrayref | ($k,$v) = each $arrayref | + |----------------------------+---------------------------| + +This allows these builtin functions to act on long dereferencing chains +or on the return value of subroutines without needing to wrap them in +C<@{}> or C<%{}>: + + push @{$obj->tags}, $new_tag; # old way + push $obj->tags, $new_tag; # new way + + for ( keys %{$hoh->{genres}{artists}} ) {...} # old way + for ( keys $hoh->{genres}{artists} ) {...} # new way + +=head3 Single term prototype + +The C<+> prototype is a special alternative to C<$> that acts like +C<\[@%]> when given a literal array or hash variable, but will otherwise +force scalar context on the argument. See L<perlsub/Prototypes>. + +=head3 C<package> block syntax + +A package declaration can now contain a code block, in which case the +declaration is in scope inside that block only. So C<package Foo { ... }> +is precisely equivalent to C<{ package Foo; ... }>. It also works with +a version number in the declaration, as in C<package Foo 1.2 { ... }>, +which is its most attractive feature. See L<perlfunc>. + +=head3 Statement labels can appear in more places + +Statement labels can now occur before any type of statement or declaration, +such as C<package>. + +=head3 Stacked labels + +Multiple statement labels can now appear before a single statement. + +=head3 Uppercase X/B allowed in hexadecimal/binary literals + +Literals may now use either upper case C<0X...> or C<0B...> prefixes, +in addition to the already supported C<0x...> and C<0b...> +syntax [perl #76296]. + +C, Ruby, Python, and PHP already support this syntax, and it makes +Perl more internally consistent: a round-trip with C<eval sprintf +"%#X", 0x10> now returns C<16>, just like C<eval sprintf "%#x", 0x10>. + +=head3 Overridable tie functions + +C<tie>, C<tied> and C<untie> can now be overridden [perl #75902]. + +=head2 Exception Handling + +To make them more reliable and consistent, several changes have been made +to how C<die>, C<warn>, and C<$@> behave. + +=over + +=item * + +When an exception is thrown inside an C<eval>, the exception is no +longer at risk of being clobbered by destructor code running during unwinding. +Previously, the exception was written into C<$@> +early in the throwing process, and would be overwritten if C<eval> was +used internally in the destructor for an object that had to be freed +while exiting from the outer C<eval>. Now the exception is written +into C<$@> last thing before exiting the outer C<eval>, so the code +running immediately thereafter can rely on the value in C<$@> correctly +corresponding to that C<eval>. (C<$@> is still also set before exiting the +C<eval>, for the sake of destructors that rely on this.) + +Likewise, a C<local $@> inside an C<eval> no longer clobbers any +exception thrown in its scope. Previously, the restoration of C<$@> upon +unwinding would overwrite any exception being thrown. Now the exception +gets to the C<eval> anyway. So C<local $@> is safe before a C<die>. + +Exceptions thrown from object destructors no longer modify the C<$@> +of the surrounding context. (If the surrounding context was exception +unwinding, this used to be another way to clobber the exception being +thrown.) Previously such an exception was +sometimes emitted as a warning, and then either was +string-appended to the surrounding C<$@> or completely replaced the +surrounding C<$@>, depending on whether that exception and the surrounding +C<$@> were strings or objects. Now, an exception in this situation is +always emitted as a warning, leaving the surrounding C<$@> untouched. +In addition to object destructors, this also affects any function call +run by XS code using the C<G_KEEPERR> flag. + +=item * + +Warnings for C<warn> can now be objects in the same way as exceptions +for C<die>. If an object-based warning gets the default handling +of writing to standard error, it is stringified as before with the +filename and line number appended. But a C<$SIG{__WARN__}> handler now +receives an object-based warning as an object, where previously it +was passed the result of stringifying the object. + +=back + +=head2 Other Enhancements + +=head3 Assignment to C<$0> sets the legacy process name with prctl() on Linux + +On Linux the legacy process name is now set with L<prctl(2)>, in +addition to altering the POSIX name via C<argv[0]>, as Perl has done +since version 4.000. Now system utilities that read the legacy process +name such as I<ps>, I<top>, and I<killall> recognize the name you set when +assigning to C<$0>. The string you supply is truncated at 16 bytes; +this limitation is imposed by Linux. + +=head3 srand() now returns the seed + +This allows programs that need to have repeatable results not to have to come +up with their own seed-generating mechanism. Instead, they can use srand() +and stash the return value for future use. One example is a test program with +too many combinations to test comprehensively in the time available for +each run. It can test a random subset each time and, should there be a failure, +log the seed used for that run so this can later be used to produce the same results. + +=head3 printf-like functions understand post-1980 size modifiers + +Perl's printf and sprintf operators, and Perl's internal printf replacement +function, now understand the C90 size modifiers "hh" (C<char>), "z" +(C<size_t>), and "t" (C<ptrdiff_t>). Also, when compiled with a C99 +compiler, Perl now understands the size modifier "j" (C<intmax_t>) +(but this is not portable). + +So, for example, on any modern machine, C<sprintf("%hhd", 257)> returns "1". + +=head3 New global variable C<${^GLOBAL_PHASE}> + +A new global variable, C<${^GLOBAL_PHASE}>, has been added to allow +introspection of the current phase of the Perl interpreter. It's explained in +detail in L<perlvar/"${^GLOBAL_PHASE}"> and in +L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">. + +=head3 C<-d:-foo> calls C<Devel::foo::unimport> + +The syntax B<-d:foo> was extended in 5.6.1 to make B<-d:foo=bar> +equivalent to B<-MDevel::foo=bar>, which expands +internally to C<use Devel::foo 'bar'>. +Perl now allows prefixing the module name with B<->, with the same +semantics as B<-M>; that is: + +=over 4 + +=item C<-d:-foo> + +Equivalent to B<-M-Devel::foo>: expands to +C<no Devel::foo> and calls C<< Devel::foo->unimport() >> +if that method exists. + +=item C<-d:-foo=bar> + +Equivalent to B<-M-Devel::foo=bar>: expands to C<no Devel::foo 'bar'>, +and calls C<< Devel::foo->unimport("bar") >> if that method exists. + +=back + +This is particularly useful for suppressing the default actions of a +C<Devel::*> module's C<import> method whilst still loading it for debugging. + +=head3 Filehandle method calls load L<IO::File> on demand + +When a method call on a filehandle would die because the method cannot +be resolved and L<IO::File> has not been loaded, Perl now loads L<IO::File> +via C<require> and attempts method resolution again: + + open my $fh, ">", $file; + $fh->binmode(":raw"); # loads IO::File and succeeds + +This also works for globs like C<STDOUT>, C<STDERR>, and C<STDIN>: + + STDOUT->autoflush(1); + +Because this on-demand load happens only if method resolution fails, the +legacy approach of manually loading an L<IO::File> parent class for partial +method support still works as expected: + + use IO::Handle; + open my $fh, ">", $file; + $fh->autoflush(1); # IO::File not loaded + +=head3 Improved IPv6 support + +The C<Socket> module provides new affordances for IPv6, +including implementations of the C<Socket::getaddrinfo()> and +C<Socket::getnameinfo()> functions, along with related constants and a +handful of new functions. See L<Socket>. + +=head3 DTrace probes now include package name + +The C<DTrace> probes now include an additional argument, C<arg3>, which contains +the package the subroutine being entered or left was compiled in. + +For example, using the following DTrace script: + + perl$target:::sub-entry + { + printf("%s::%s\n", copyinstr(arg0), copyinstr(arg3)); + } + +and then running: + + $ perl -e 'sub test { }; test' + +C<DTrace> will print: + + main::test + +=head2 New C APIs + +See L</Internal Changes>. + +=head1 Security + +=head2 User-defined regular expression properties + +L<perlunicode/"User-Defined Character Properties"> documented that you can +create custom properties by defining subroutines whose names begin with +"In" or "Is". However, Perl did not actually enforce that naming +restriction, so C<\p{foo::bar}> could call foo::bar() if it existed. The documented +convention is now enforced. + +Also, Perl no longer allows tainted regular expressions to invoke a +user-defined property. It simply dies instead [perl #82616]. + +=head1 Incompatible Changes + +Perl 5.14.0 is not binary-compatible with any previous stable release. + +In addition to the sections that follow, see L</C API Changes>. + +=head2 Regular Expressions and String Escapes + +=head3 Inverted bracketed character classes and multi-character folds + +Some characters match a sequence of two or three characters in C</i> +regular expression matching under Unicode rules. One example is +C<LATIN SMALL LETTER SHARP S> which matches the sequence C<ss>. + + 'ss' =~ /\A[\N{LATIN SMALL LETTER SHARP S}]\z/i # Matches + +This, however, can lead to very counter-intuitive results, especially +when inverted. Because of this, Perl 5.14 does not use multi-character C</i> +matching in inverted character classes. + + 'ss' =~ /\A[^\N{LATIN SMALL LETTER SHARP S}]+\z/i # ??? + +This should match any sequences of characters that aren't the C<SHARP S> +nor what C<SHARP S> matches under C</i>. C<"s"> isn't C<SHARP S>, but +Unicode says that C<"ss"> is what C<SHARP S> matches under C</i>. So +which one "wins"? Do you fail the match because the string has C<ss> or +accept it because it has an C<s> followed by another C<s>? + +Earlier releases of Perl did allow this multi-character matching, +but due to bugs, it mostly did not work. + +=head3 \400-\777 + +In certain circumstances, C<\400>-C<\777> in regexes have behaved +differently than they behave in all other doublequote-like contexts. +Since 5.10.1, Perl has issued a deprecation warning when this happens. +Now, these literals behave the same in all doublequote-like contexts, +namely to be equivalent to C<\x{100}>-C<\x{1FF}>, with no deprecation +warning. + +Use of C<\400>-C<\777> in the command-line option B<-0> retain their +conventional meaning. They slurp whole input files; previously, this +was documented only for B<-0777>. + +Because of various ambiguities, you should use the new +C<\o{...}> construct to represent characters in octal instead. + +=head3 Most C<\p{}> properties are now immune to case-insensitive matching + +For most Unicode properties, it doesn't make sense to have them match +differently under C</i> case-insensitive matching. Doing so can lead +to unexpected results and potential security holes. For example + + m/\p{ASCII_Hex_Digit}+/i + +could previously match non-ASCII characters because of the Unicode +matching rules (although there were several bugs with this). Now +matching under C</i> gives the same results as non-C</i> matching except +for those few properties where people have come to expect differences, +namely the ones where casing is an integral part of their meaning, such +as C<m/\p{Uppercase}/i> and C<m/\p{Lowercase}/i>, both of which match +the same code points as matched by C<m/\p{Cased}/i>. +Details are in L<perlrecharclass/Unicode Properties>. + +User-defined property handlers that need to match differently under C</i> +must be changed to read the new boolean parameter passed to them, which +is non-zero if case-insensitive matching is in effect and 0 otherwise. +See L<perlunicode/User-Defined Character Properties>. + +=head3 \p{} implies Unicode semantics + +Specifying a Unicode property in the pattern indicates +that the pattern is meant for matching according to Unicode rules, the way +C<\N{I<NAME>}> does. + +=head3 Regular expressions retain their localeness when interpolated + +Regular expressions compiled under C<use locale> now retain this when +interpolated into a new regular expression compiled outside a +C<use locale>, and vice-versa. + +Previously, one regular expression interpolated into another inherited +the localeness of the surrounding regex, losing whatever state it +originally had. This is considered a bug fix, but may trip up code that +has come to rely on the incorrect behaviour. + +=head3 Stringification of regexes has changed + +Default regular expression modifiers are now notated using +C<(?^...)>. Code relying on the old stringification will fail. +This is so that when new modifiers are added, such code won't +have to keep changing each time this happens, because the stringification +will automatically incorporate the new modifiers. + +Code that needs to work properly with both old- and new-style regexes +can avoid the whole issue by using (for perls since 5.9.5; see L<re>): + + use re qw(regexp_pattern); + my ($pat, $mods) = regexp_pattern($re_ref); + +If the actual stringification is important or older Perls need to be +supported, you can use something like the following: + + # Accept both old and new-style stringification + my $modifiers = (qr/foobar/ =~ /\Q(?^/) ? "^" : "-xism"; + +And then use C<$modifiers> instead of C<-xism>. + +=head3 Run-time code blocks in regular expressions inherit pragmata + +Code blocks in regular expressions (C<(?{...})> and C<(??{...})>) previously +did not inherit pragmata (strict, warnings, etc.) if the regular expression +was compiled at run time as happens in cases like these two: + + use re "eval"; + $foo =~ $bar; # when $bar contains (?{...}) + $foo =~ /$bar(?{ $finished = 1 })/; + +This bug has now been fixed, but code that relied on the buggy behaviour +may need to be fixed to account for the correct behaviour. + +=head2 Stashes and Package Variables + +=head3 Localised tied hashes and arrays are no longed tied + +In the following: + + tie @a, ...; + { + local @a; + # here, @a is a now a new, untied array + } + # here, @a refers again to the old, tied array + +Earlier versions of Perl incorrectly tied the new local array. This has +now been fixed. This fix could however potentially cause a change in +behaviour of some code. + +=head3 Stashes are now always defined + +C<defined %Foo::> now always returns true, even when no symbols have yet been +defined in that package. + +This is a side-effect of removing a special-case kludge in the tokeniser, +added for 5.10.0, to hide side-effects of changes to the internal storage of +hashes. The fix drastically reduces hashes' memory overhead. + +Calling defined on a stash has been deprecated since 5.6.0, warned on +lexicals since 5.6.0, and warned for stashes and other package +variables since 5.12.0. C<defined %hash> has always exposed an +implementation detail: emptying a hash by deleting all entries from it does +not make C<defined %hash> false. Hence C<defined %hash> is not valid code to +determine whether an arbitrary hash is empty. Instead, use the behaviour +of an empty C<%hash> always returning false in scalar context. + +=head3 Clearing stashes + +Stash list assignment C<%foo:: = ()> used to make the stash temporarily +anonymous while it was being emptied. Consequently, any of its +subroutines referenced elsewhere would become anonymous, showing up as +"(unknown)" in C<caller>. They now retain their package names such that +C<caller> returns the original sub name if there is still a reference +to its typeglob and "foo::__ANON__" otherwise [perl #79208]. + +=head3 Dereferencing typeglobs + +If you assign a typeglob to a scalar variable: + + $glob = *foo; + +the glob that is copied to C<$glob> is marked with a special flag +indicating that the glob is just a copy. This allows subsequent +assignments to C<$glob> to overwrite the glob. The original glob, +however, is immutable. + +Some Perl operators did not distinguish between these two types of globs. +This would result in strange behaviour in edge cases: C<untie $scalar> +would not untie the scalar if the last thing assigned to it was a glob +(because it treated it as C<untie *$scalar>, which unties a handle). +Assignment to a glob slot (such as C<*$glob = \@some_array>) would simply +assign C<\@some_array> to C<$glob>. + +To fix this, the C<*{}> operator (including its C<*foo> and C<*$foo> forms) +has been modified to make a new immutable glob if its operand is a glob +copy. This allows operators that make a distinction between globs and +scalars to be modified to treat only immutable globs as globs. (C<tie>, +C<tied> and C<untie> have been left as they are for compatibility's sake, +but will warn. See L</Deprecations>.) + +This causes an incompatible change in code that assigns a glob to the +return value of C<*{}> when that operator was passed a glob copy. Take the +following code, for instance: + + $glob = *foo; + *$glob = *bar; + +The C<*$glob> on the second line returns a new immutable glob. That new +glob is made an alias to C<*bar>. Then it is discarded. So the second +assignment has no effect. + +See L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=77810> for +more detail. + +=head3 Magic variables outside the main package + +In previous versions of Perl, magic variables like C<$!>, C<%SIG>, etc. would +"leak" into other packages. So C<%foo::SIG> could be used to access signals, +C<${"foo::!"}> (with strict mode off) to access C's C<errno>, etc. + +This was a bug, or an "unintentional" feature, which caused various ill effects, +such as signal handlers being wiped when modules were loaded, etc. + +This has been fixed (or the feature has been removed, depending on how you see +it). + +=head3 local($_) strips all magic from $_ + +local() on scalar variables gives them a new value but keeps all +their magic intact. This has proven problematic for the default +scalar variable $_, where L<perlsub> recommends that any subroutine +that assigns to $_ should first localize it. This would throw an +exception if $_ is aliased to a read-only variable, and could in general have +various unintentional side-effects. + +Therefore, as an exception to the general rule, local($_) will not +only assign a new value to $_, but also remove all existing magic from +it as well. + +=head3 Parsing of package and variable names + +Parsing the names of packages and package variables has changed: +multiple adjacent pairs of colons, as in C<foo::::bar>, are now all +treated as package separators. + +Regardless of this change, the exact parsing of package separators has +never been guaranteed and is subject to change in future Perl versions. + +=head2 Changes to Syntax or to Perl Operators + +=head3 C<given> return values + +C<given> blocks now return the last evaluated +expression, or an empty list if the block was exited by C<break>. Thus you +can now write: + + my $type = do { + given ($num) { + break when undef; + "integer" when /^[+-]?[0-9]+$/; + "float" when /^[+-]?[0-9]+(?:\.[0-9]+)?$/; + "unknown"; + } + }; + +See L<perlsyn/Return value> for details. + +=head3 Change in parsing of certain prototypes + +Functions declared with the following prototypes now behave correctly as unary +functions: + + * + \$ \% \@ \* \& + \[...] + ;$ ;* + ;\$ ;\% etc. + ;\[...] + +Due to this bug fix [perl #75904], functions +using the C<(*)>, C<(;$)> and C<(;*)> prototypes +are parsed with higher precedence than before. So +in the following example: + + sub foo(;$); + foo $a < $b; + +the second line is now parsed correctly as C<< foo($a) < $b >>, rather than +C<< foo($a < $b) >>. This happens when one of these operators is used in +an unparenthesised argument: + + < > <= >= lt gt le ge + == != <=> eq ne cmp ~~ + & + | ^ + && + || // + .. ... + ?: + = += -= *= etc. + , => + +=head3 Smart-matching against array slices + +Previously, the following code resulted in a successful match: + + my @a = qw(a y0 z); + my @b = qw(a x0 z); + @a[0 .. $#b] ~~ @b; + +This odd behaviour has now been fixed [perl #77468]. + +=head3 Negation treats strings differently from before + +The unary negation operator, C<->, now treats strings that look like numbers +as numbers [perl #57706]. + +=head3 Negative zero + +Negative zero (-0.0), when converted to a string, now becomes "0" on all +platforms. It used to become "-0" on some, but "0" on others. + +If you still need to determine whether a zero is negative, use +C<sprintf("%g", $zero) =~ /^-/> or the L<Data::Float> module on CPAN. + +=head3 C<:=> is now a syntax error + +Previously C<my $pi := 4> was exactly equivalent to C<my $pi : = 4>, +with the C<:> being treated as the start of an attribute list, ending before +the C<=>. The use of C<:=> to mean C<: => was deprecated in 5.12.0, and is +now a syntax error. This allows future use of C<:=> as a new token. + +Outside the core's tests for it, we find no Perl 5 code on CPAN +using this construction, so we believe that this change will have +little impact on real-world codebases. + +If it is absolutely necessary to have empty attribute lists (for example, +because of a code generator), simply avoid the error by adding a space before +the C<=>. + +=head3 Change in the parsing of identifiers + +Characters outside the Unicode "XIDStart" set are no longer allowed at the +beginning of an identifier. This means that certain accents and marks +that normally follow an alphabetic character may no longer be the first +character of an identifier. + +=head2 Threads and Processes + +=head3 Directory handles not copied to threads + +On systems other than Windows that do not have +a C<fchdir> function, newly-created threads no +longer inherit directory handles from their parent threads. Such programs +would usually have crashed anyway [perl #75154]. + +=head3 C<close> on shared pipes + +To avoid deadlocks, the C<close> function no longer waits for the +child process to exit if the underlying file descriptor is still +in use by another thread. It returns true in such cases. + +=head3 fork() emulation will not wait for signalled children + +On Windows parent processes would not terminate until all forked +children had terminated first. However, C<kill("KILL", ...)> is +inherently unstable on pseudo-processes, and C<kill("TERM", ...)> +might not get delivered if the child is blocked in a system call. + +To avoid the deadlock and still provide a safe mechanism to terminate +the hosting process, Perl now no longer waits for children that +have been sent a SIGTERM signal. It is up to the parent process to +waitpid() for these children if child-cleanup processing must be +allowed to finish. However, it is also then the responsibility of the +parent to avoid the deadlock by making sure the child process +can't be blocked on I/O. + +See L<perlfork> for more information about the fork() emulation on +Windows. + +=head2 Configuration + +=head3 Naming fixes in Policy_sh.SH may invalidate Policy.sh + +Several long-standing typos and naming confusions in F<Policy_sh.SH> have +been fixed, standardizing on the variable names used in F<config.sh>. + +This will change the behaviour of F<Policy.sh> if you happen to have been +accidentally relying on its incorrect behaviour. + +=head3 Perl source code is read in text mode on Windows + +Perl scripts used to be read in binary mode on Windows for the benefit +of the L<ByteLoader> module (which is no longer part of core Perl). This +had the side-effect of breaking various operations on the C<DATA> filehandle, +including seek()/tell(), and even simply reading from C<DATA> after filehandles +have been flushed by a call to system(), backticks, fork() etc. + +The default build options for Windows have been changed to read Perl source +code on Windows in text mode now. L<ByteLoader> will (hopefully) be updated on +CPAN to automatically handle this situation [perl #28106]. + +=head1 Deprecations + +See also L</Deprecated C APIs>. + +=head2 Omitting a space between a regular expression and subsequent word + +Omitting the space between a regular expression operator or +its modifiers and the following word is deprecated. For +example, C<< m/foo/sand $bar >> is for now still parsed +as C<< m/foo/s and $bar >>, but will now issue a warning. + +=head2 C<\cI<X>> + +The backslash-c construct was designed as a way of specifying +non-printable characters, but there were no restrictions (on ASCII +platforms) on what the character following the C<c> could be. Now, +a deprecation warning is raised if that character isn't an ASCII character. +Also, a deprecation warning is raised for C<"\c{"> (which is the same +as simply saying C<";">). + +=head2 C<"\b{"> and C<"\B{"> + +In regular expressions, a literal C<"{"> immediately following a C<"\b"> +(not in a bracketed character class) or a C<"\B{"> is now deprecated +to allow for its future use by Perl itself. + +=head2 Perl 4-era .pl libraries + +Perl bundles a handful of library files that predate Perl 5. +This bundling is now deprecated for most of these files, which are now +available from CPAN. The affected files now warn when run, if they were +installed as part of the core. + +This is a mandatory warning, not obeying B<-X> or lexical warning bits. +The warning is modelled on that supplied by F<deprecate.pm> for +deprecated-in-core F<.pm> libraries. It points to the specific CPAN +distribution that contains the F<.pl> libraries. The CPAN versions, of +course, do not generate the warning. + +=head2 List assignment to C<$[> + +Assignment to C<$[> was deprecated and started to give warnings in +Perl version 5.12.0. This version of Perl (5.14) now also emits a warning +when assigning to C<$[> in list context. This fixes an oversight in 5.12.0. + +=head2 Use of qw(...) as parentheses + +Historically the parser fooled itself into thinking that C<qw(...)> literals +were always enclosed in parentheses, and as a result you could sometimes omit +parentheses around them: + + for $x qw(a b c) { ... } + +The parser no longer lies to itself in this way. Wrap the list literal in +parentheses like this: + + for $x (qw(a b c)) { ... } + +This is being deprecated because the parentheses in C<for $i (1,2,3) { ... }> +are not part of expression syntax. They are part of the statement +syntax, with the C<for> statement wanting literal parentheses. +The synthetic parentheses that a C<qw> expression acquired were only +intended to be treated as part of expression syntax. + +Note that this does not change the behaviour of cases like: + + use POSIX qw(setlocale localeconv); + our @EXPORT = qw(foo bar baz); + +where parentheses were never required around the expression. + +=head2 C<\N{BELL}> + +This is because Unicode is using that name for a different character. +See L</Unicode Version 6.0 is now supported (mostly)> for more +explanation. + +=head2 C<?PATTERN?> + +C<?PATTERN?> (without the initial C<m>) has been deprecated and now produces +a warning. This is to allow future use of C<?> in new operators. +The match-once functionality is still available as C<m?PATTERN?>. + +=head2 Tie functions on scalars holding typeglobs + +Calling a tie function (C<tie>, C<tied>, C<untie>) with a scalar argument +acts on a filehandle if the scalar happens to hold a typeglob. + +This is a long-standing bug that will be removed in Perl 5.16, as +there is currently no way to tie the scalar itself when it holds +a typeglob, and no way to untie a scalar that has had a typeglob +assigned to it. + +Now there is a deprecation warning whenever a tie +function is used on a handle without an explicit C<*>. + +=head2 User-defined case-mapping + +This feature is being deprecated due to its many issues, as documented in +L<perlunicode/User-Defined Case Mappings (for serious hackers only)>. +This feature will be removed in Perl 5.16. Instead use the CPAN module +L<Unicode::Casing>, which provides improved functionality. + +=head2 Deprecated modules + +The following module will be removed from the core distribution in a +future release, and should be installed from CPAN instead. Distributions +on CPAN that require this should add it to their prerequisites. The +core version of these module now issues a deprecation warning. + +If you ship a packaged version of Perl, either alone or as part of a +larger system, then you should carefully consider the repercussions of +core module deprecations. You may want to consider shipping your default +build of Perl with a package for the deprecated module that +installs into C<vendor> or C<site> Perl library directories. This will +inhibit the deprecation warnings. + +Alternatively, you may want to consider patching F<lib/deprecate.pm> +to provide deprecation warnings specific to your packaging system +or distribution of Perl, consistent with how your packaging system +or distribution manages a staged transition from a release where the +installation of a single package provides the given functionality, to +a later release where the system administrator needs to know to install +multiple packages to get that same functionality. + +You can silence these deprecation warnings by installing the module +in question from CPAN. To install the latest version of it by role +rather than by name, just install C<Task::Deprecations::5_14>. + +=over + +=item L<Devel::DProf> + +We strongly recommend that you install and use L<Devel::NYTProf> instead +of L<Devel::DProf>, as L<Devel::NYTProf> offers significantly +improved profiling and reporting. + +=back + +=head1 Performance Enhancements + +=head2 "Safe signals" optimisation + +Signal dispatch has been moved from the runloop into control ops. +This should give a few percent speed increase, and eliminates nearly +all the speed penalty caused by the introduction of "safe signals" +in 5.8.0. Signals should still be dispatched within the same +statement as they were previously. If this does I<not> happen, or +if you find it possible to create uninterruptible loops, this is a +bug, and reports are encouraged of how to recreate such issues. + +=head2 Optimisation of shift() and pop() calls without arguments + +Two fewer OPs are used for shift() and pop() calls with no argument (with +implicit C<@_>). This change makes shift() 5% faster than C<shift @_> +on non-threaded perls, and 25% faster on threaded ones. + +=head2 Optimisation of regexp engine string comparison work + +The C<foldEQ_utf8> API function for case-insensitive comparison of strings (which +is used heavily by the regexp engine) was substantially refactored and +optimised -- and its documentation much improved as a free bonus. + +=head2 Regular expression compilation speed-up + +Compiling regular expressions has been made faster when upgrading +the regex to utf8 is necessary but this isn't known when the compilation begins. + +=head2 String appending is 100 times faster + +When doing a lot of string appending, perls built to use the system's +C<malloc> could end up allocating a lot more memory than needed in a +inefficient way. + +C<sv_grow>, the function used to allocate more memory if necessary +when appending to a string, has been taught to round up the memory +it requests to a certain geometric progression, making it much faster on +certain platforms and configurations. On Win32, it's now about 100 times +faster. + +=head2 Eliminate C<PL_*> accessor functions under ithreads + +When C<MULTIPLICITY> was first developed, and interpreter state moved into +an interpreter struct, thread- and interpreter-local C<PL_*> variables +were defined as macros that called accessor functions (returning the +address of the value) outside the Perl core. The intent was to allow +members within the interpreter struct to change size without breaking +binary compatibility, so that bug fixes could be merged to a maintenance +branch that necessitated such a size change. This mechanism was redundant +and penalised well-behaved code. It has been removed. + +=head2 Freeing weak references + +When there are many weak references to an object, freeing that object +can under some circumstances take O(I<NE<0xB2>>) time to free, where +I<N> is the number of references. The circumstances in which this can happen +have been reduced [perl #75254] + +=head2 Lexical array and hash assignments + +An earlier optimisation to speed up C<my @array = ...> and +C<my %hash = ...> assignments caused a bug and was disabled in Perl 5.12.0. + +Now we have found another way to speed up these assignments [perl #82110]. + +=head2 C<@_> uses less memory + +Previously, C<@_> was allocated for every subroutine at compile time with +enough space for four entries. Now this allocation is done on demand when +the subroutine is called [perl #72416]. + +=head2 Size optimisations to SV and HV structures + +C<xhv_fill> has been eliminated from C<struct xpvhv>, saving 1 IV per hash and +on some systems will cause C<struct xpvhv> to become cache-aligned. To avoid +this memory saving causing a slowdown elsewhere, boolean use of C<HvFILL> +now calls C<HvTOTALKEYS> instead (which is equivalent), so while the fill +data when actually required are now calculated on demand, cases when +this needs to be done should be rare. + +The order of structure elements in SV bodies has changed. Effectively, +the NV slot has swapped location with STASH and MAGIC. As all access to +SV members is via macros, this should be completely transparent. This +change allows the space saving for PVHVs documented above, and may reduce +the memory allocation needed for PVIVs on some architectures. + +C<XPV>, C<XPVIV>, and C<XPVNV> now allocate only the parts of the C<SV> body +they actually use, saving some space. + +Scalars containing regular expressions now allocate only the part of the C<SV> +body they actually use, saving some space. + +=head2 Memory consumption improvements to Exporter + +The C<@EXPORT_FAIL> AV is no longer created unless needed, hence neither is +the typeglob backing it. This saves about 200 bytes for every package that +uses Exporter but doesn't use this functionality. + +=head2 Memory savings for weak references + +For weak references, the common case of just a single weak reference +per referent has been optimised to reduce the storage required. In this +case it saves the equivalent of one small Perl array per referent. + +=head2 C<%+> and C<%-> use less memory + +The bulk of the C<Tie::Hash::NamedCapture> module used to be in the Perl +core. It has now been moved to an XS module to reduce overhead for +programs that do not use C<%+> or C<%->. + +=head2 Multiple small improvements to threads + +The internal structures of threading now make fewer API calls and fewer +allocations, resulting in noticeably smaller object code. Additionally, +many thread context checks have been deferred so they're done only +as needed (although this is only possible for non-debugging builds). + +=head2 Adjacent pairs of nextstate opcodes are now optimized away + +Previously, in code such as + + use constant DEBUG => 0; + + sub GAK { + warn if DEBUG; + print "stuff\n"; + } + +the ops for C<warn if DEBUG> would be folded to a C<null> op (C<ex-const>), but +the C<nextstate> op would remain, resulting in a runtime op dispatch of +C<nextstate>, C<nextstate>, etc. + +The execution of a sequence of C<nextstate> ops is indistinguishable from just +the last C<nextstate> op so the peephole optimizer now eliminates the first of +a pair of C<nextstate> ops except when the first carries a label, since labels +must not be eliminated by the optimizer, and label usage isn't conclusively known +at compile time. + +=head1 Modules and Pragmata + +=head2 New Modules and Pragmata + +=over 4 + +=item * + +L<CPAN::Meta::YAML> 0.003 has been added as a dual-life module. It supports a +subset of YAML sufficient for reading and writing F<META.yml> and F<MYMETA.yml> files +included with CPAN distributions or generated by the module installation +toolchain. It should not be used for any other general YAML parsing or +generation task. + +=item * + +L<CPAN::Meta> version 2.110440 has been added as a dual-life module. It +provides a standard library to read, interpret and write CPAN distribution +metadata files (like F<META.json> and F<META.yml)> that describe a +distribution, its contents, and the requirements for building it and +installing it. The latest CPAN distribution metadata specification is +included as L<CPAN::Meta::Spec> and notes on changes in the specification +over time are given in L<CPAN::Meta::History>. + +=item * + +L<HTTP::Tiny> 0.012 has been added as a dual-life module. It is a very +small, simple HTTP/1.1 client designed for simple GET requests and file +mirroring. It has been added so that F<CPAN.pm> and L<CPANPLUS> can +"bootstrap" HTTP access to CPAN using pure Perl without relying on external +binaries like L<curl(1)> or L<wget(1)>. + +=item * + +L<JSON::PP> 2.27105 has been added as a dual-life module to allow CPAN +clients to read F<META.json> files in CPAN distributions. + +=item * + +L<Module::Metadata> 1.000004 has been added as a dual-life module. It gathers +package and POD information from Perl module files. It is a standalone module +based on L<Module::Build::ModuleInfo> for use by other module installation +toolchain components. L<Module::Build::ModuleInfo> has been deprecated in +favor of this module instead. + +=item * + +L<Perl::OSType> 1.002 has been added as a dual-life module. It maps Perl +operating system names (like "dragonfly" or "MSWin32") to more generic types +with standardized names (like "Unix" or "Windows"). It has been refactored +out of L<Module::Build> and L<ExtUtils::CBuilder> and consolidates such mappings into +a single location for easier maintenance. + +=item * + +The following modules were added by the L<Unicode::Collate> +upgrade. See below for details. + +L<Unicode::Collate::CJK::Big5> + +L<Unicode::Collate::CJK::GB2312> + +L<Unicode::Collate::CJK::JISX0208> + +L<Unicode::Collate::CJK::Korean> + +L<Unicode::Collate::CJK::Pinyin> + +L<Unicode::Collate::CJK::Stroke> + +=item * + +L<Version::Requirements> version 0.101020 has been added as a dual-life +module. It provides a standard library to model and manipulates module +prerequisites and version constraints defined in L<CPAN::Meta::Spec>. + +=back + +=head2 Updated Modules and Pragma + +=over 4 + +=item * + +L<attributes> has been upgraded from version 0.12 to 0.14. + +=item * + +L<Archive::Extract> has been upgraded from version 0.38 to 0.48. + +Updates since 0.38 include: a safe print method that guards +L<Archive::Extract> from changes to C<$\>; a fix to the tests when run in core +Perl; support for TZ files; a modification for the lzma +logic to favour L<IO::Uncompress::Unlzma>; and a fix +for an issue with NetBSD-current and its new L<unzip(1)> +executable. + +=item * + +L<Archive::Tar> has been upgraded from version 1.54 to 1.76. + +Important changes since 1.54 include the following: + +=over + +=item * + +Compatibility with busybox implementations of L<tar(1)>. + +=item * + +A fix so that write() and create_archive() +close only filehandles they themselves opened. + +=item * + +A bug was fixed regarding the exit code of extract_archive. + +=item * + +The L<ptar(1)> utility has a new option to allow safe creation of +tarballs without world-writable files on Windows, allowing those +archives to be uploaded to CPAN. + +=item * + +A new L<ptargrep(1)> utility for using regular expressions against +the contents of files in a tar archive. + +=item * + +L<pax> extended headers are now skipped. + +=back + +=item * + +L<Attribute::Handlers> has been upgraded from version 0.87 to 0.89. + +=item * + +L<autodie> has been upgraded from version 2.06_01 to 2.1001. + +=item * + +L<AutoLoader> has been upgraded from version 5.70 to 5.71. + +=item * + +The L<B> module has been upgraded from version 1.23 to 1.29. + +It no longer crashes when taking apart a C<y///> containing characters +outside the octet range or compiled in a C<use utf8> scope. + +The size of the shared object has been reduced by about 40%, with no +reduction in functionality. + +=item * + +L<B::Concise> has been upgraded from version 0.78 to 0.83. + +L<B::Concise> marks rv2sv(), rv2av(), and rv2hv() ops with the new +C<OPpDEREF> flag as "DREFed". + +It no longer produces mangled output with the B<-tree> option +[perl #80632]. + +=item * + +L<B::Debug> has been upgraded from version 1.12 to 1.16. + +=item * + +L<B::Deparse> has been upgraded from version 0.96 to 1.03. + +The deparsing of a C<nextstate> op has changed when it has both a +change of package relative to the previous nextstate, or a change of +C<%^H> or other state and a label. The label was previously emitted +first, but is now emitted last (5.12.1). + +The C<no 5.13.2> or similar form is now correctly handled by L<B::Deparse> +(5.12.3). + +L<B::Deparse> now properly handles the code that applies a conditional +pattern match against implicit C<$_> as it was fixed in [perl #20444]. + +Deparsing of C<our> followed by a variable with funny characters +(as permitted under the C<use utf8> pragma) has also been fixed [perl #33752]. + +=item * + +L<B::Lint> has been upgraded from version 1.11_01 to 1.13. + +=item * + +L<base> has been upgraded from version 2.15 to 2.16. + +=item * + +L<Benchmark> has been upgraded from version 1.11 to 1.12. + +=item * + +L<bignum> has been upgraded from version 0.23 to 0.27. + +=item * + +L<Carp> has been upgraded from version 1.15 to 1.20. + +L<Carp> now detects incomplete L<caller()|perlfunc/"caller EXPR"> +overrides and avoids using bogus C<@DB::args>. To provide backtraces, +Carp relies on particular behaviour of the caller() builtin. +L<Carp> now detects if other code has overridden this with an +incomplete implementation, and modifies its backtrace accordingly. +Previously incomplete overrides would cause incorrect values in +backtraces (best case), or obscure fatal errors (worst case). + +This fixes certain cases of "Bizarre copy of ARRAY" caused by modules +overriding caller() incorrectly (5.12.2). + +It now also avoids using regular expressions that cause Perl to +load its Unicode tables, so as to avoid the "BEGIN not safe after +errors" error that ensue if there has been a syntax error +[perl #82854]. + +=item * + +L<CGI> has been upgraded from version 3.48 to 3.52. + +This provides the following security fixes: the MIME boundary in +multipart_init() is now random and the handling of +newlines embedded in header values has been improved. + +=item * + +L<Compress::Raw::Bzip2> has been upgraded from version 2.024 to 2.033. + +It has been updated to use L<bzip2(1)> 1.0.6. + +=item * + +L<Compress::Raw::Zlib> has been upgraded from version 2.024 to 2.033. + +=item * + +L<constant> has been upgraded from version 1.20 to 1.21. + +Unicode constants work once more. They have been broken since Perl 5.10.0 +[CPAN RT #67525]. + +=item * + +L<CPAN> has been upgraded from version 1.94_56 to 1.9600. + +Major highlights: + +=over 4 + +=item * much less configuration dialog hassle + +=item * support for F<META/MYMETA.json> + +=item * support for L<local::lib> + +=item * support for L<HTTP::Tiny> to reduce the dependency on FTP sites + +=item * automatic mirror selection + +=item * iron out all known bugs in configure_requires + +=item * support for distributions compressed with L<bzip2(1)> + +=item * allow F<Foo/Bar.pm> on the command line to mean C<Foo::Bar> + +=back + +=item * + +L<CPANPLUS> has been upgraded from version 0.90 to 0.9103. + +A change to F<cpanp-run-perl> +resolves L<RT #55964|http://rt.cpan.org/Public/Bug/Display.html?id=55964> +and L<RT #57106|http://rt.cpan.org/Public/Bug/Display.html?id=57106>, both +of which related to failures to install distributions that use +C<Module::Install::DSL> (5.12.2). + +A dependency on L<Config> was not recognised as a +core module dependency. This has been fixed. + +L<CPANPLUS> now includes support for F<META.json> and F<MYMETA.json>. + +=item * + +L<CPANPLUS::Dist::Build> has been upgraded from version 0.46 to 0.54. + +=item * + +L<Data::Dumper> has been upgraded from version 2.125 to 2.130_02. + +The indentation used to be off when C<$Data::Dumper::Terse> was set. This +has been fixed [perl #73604]. + +This upgrade also fixes a crash when using custom sort functions that might +cause the stack to change [perl #74170]. + +L<Dumpxs> no longer crashes with globs returned by C<*$io_ref> +[perl #72332]. + +=item * + +L<DB_File> has been upgraded from version 1.820 to 1.821. + +=item * + +L<DBM_Filter> has been upgraded from version 0.03 to 0.04. + +=item * + +L<Devel::DProf> has been upgraded from version 20080331.00 to 20110228.00. + +Merely loading L<Devel::DProf> now no longer triggers profiling to start. +Both C<use Devel::DProf> and C<perl -d:DProf ...> behave as before and start +the profiler. + +B<NOTE>: L<Devel::DProf> is deprecated and will be removed from a future +version of Perl. We strongly recommend that you install and use +L<Devel::NYTProf> instead, as it offers significantly improved +profiling and reporting. + +=item * + +L<Devel::Peek> has been upgraded from version 1.04 to 1.07. + +=item * + +L<Devel::SelfStubber> has been upgraded from version 1.03 to 1.05. + +=item * + +L<diagnostics> has been upgraded from version 1.19 to 1.22. + +It now renders pod links slightly better, and has been taught to find +descriptions for messages that share their descriptions with other +messages. + +=item * + +L<Digest::MD5> has been upgraded from version 2.39 to 2.51. + +It is now safe to use this module in combination with threads. + +=item * + +L<Digest::SHA> has been upgraded from version 5.47 to 5.61. + +L<shasum> now more closely mimics L<sha1sum(1)>/L<md5sum(1)>. + +L<Addfile> accepts all POSIX filenames. + +New SHA-512/224 and SHA-512/256 transforms (ref. NIST Draft FIPS 180-4 +[February 2011]) + +=item * + +L<DirHandle> has been upgraded from version 1.03 to 1.04. + +=item * + +L<Dumpvalue> has been upgraded from version 1.13 to 1.16. + +=item * + +L<DynaLoader> has been upgraded from version 1.10 to 1.13. + +It fixes a buffer overflow when passed a very long file name. + +It no longer inherits from L<AutoLoader>; hence it no longer +produces weird error messages for unsuccessful method calls on classes that +inherit from L<DynaLoader> [perl #84358]. + +=item * + +L<Encode> has been upgraded from version 2.39 to 2.42. + +Now, all 66 Unicode non-characters are treated the same way U+FFFF has +always been treated: in cases when it was disallowed, all 66 are +disallowed, and in cases where it warned, all 66 warn. + +=item * + +L<Env> has been upgraded from version 1.01 to 1.02. + +=item * + +L<Errno> has been upgraded from version 1.11 to 1.13. + +The implementation of L<Errno> has been refactored to use about 55% less memory. + +On some platforms with unusual header files, like Win32 L<gcc(1)> using C<mingw64> +headers, some constants that weren't actually error numbers have been exposed +by L<Errno>. This has been fixed [perl #77416]. + +=item * + +L<Exporter> has been upgraded from version 5.64_01 to 5.64_03. + +Exporter no longer overrides C<$SIG{__WARN__}> [perl #74472] + +=item * + +L<ExtUtils::CBuilder> has been upgraded from version 0.27 to 0.280203. + +=item * + +L<ExtUtils::Command> has been upgraded from version 1.16 to 1.17. + +=item * + +L<ExtUtils::Constant> has been upgraded from 0.22 to 0.23. + +The L<AUTOLOAD> helper code generated by C<ExtUtils::Constant::ProxySubs> +can now croak() for missing constants, or generate a complete C<AUTOLOAD> +subroutine in XS, allowing simplification of many modules that use it +(L<Fcntl>, L<File::Glob>, L<GDBM_File>, L<I18N::Langinfo>, L<POSIX>, +L<Socket>). + +L<ExtUtils::Constant::ProxySubs> can now optionally push the names of all +constants onto the package's C<@EXPORT_OK>. + +=item * + +L<ExtUtils::Install> has been upgraded from version 1.55 to 1.56. + +=item * + +L<ExtUtils::MakeMaker> has been upgraded from version 6.56 to 6.57_05. + +=item * + +L<ExtUtils::Manifest> has been upgraded from version 1.57 to 1.58. + +=item * + +L<ExtUtils::ParseXS> has been upgraded from version 2.21 to 2.2210. + +=item * + +L<Fcntl> has been upgraded from version 1.06 to 1.11. + +=item * + +L<File::Basename> has been upgraded from version 2.78 to 2.82. + +=item * + +L<File::CheckTree> has been upgraded from version 4.4 to 4.41. + +=item * + +L<File::Copy> has been upgraded from version 2.17 to 2.21. + +=item * + +L<File::DosGlob> has been upgraded from version 1.01 to 1.04. + +It allows patterns containing literal parentheses: they no longer need to +be escaped. On Windows, it no longer +adds an extra F<./> to file names +returned when the pattern is a relative glob with a drive specification, +like F<C:*.pl> [perl #71712]. + +=item * + +L<File::Fetch> has been upgraded from version 0.24 to 0.32. + +L<HTTP::Lite> is now supported for the "http" scheme. + +The L<fetch(1)> utility is supported on FreeBSD, NetBSD, and +Dragonfly BSD for the C<http> and C<ftp> schemes. + +=item * + +L<File::Find> has been upgraded from version 1.15 to 1.19. + +It improves handling of backslashes on Windows, so that paths like +F<C:\dir\/file> are no longer generated [perl #71710]. + +=item * + +L<File::Glob> has been upgraded from version 1.07 to 1.12. + +=item * + +L<File::Spec> has been upgraded from version 3.31 to 3.33. + +Several portability fixes were made in L<File::Spec::VMS>: a colon is now +recognized as a delimiter in native filespecs; caret-escaped delimiters are +recognized for better handling of extended filespecs; catpath() returns +an empty directory rather than the current directory if the input directory +name is empty; and abs2rel() properly handles Unix-style input (5.12.2). + +=item * + +L<File::stat> has been upgraded from 1.02 to 1.05. + +The C<-x> and C<-X> file test operators now work correctly when run +by the superuser. + +=item * + +L<Filter::Simple> has been upgraded from version 0.84 to 0.86. + +=item * + +L<GDBM_File> has been upgraded from 1.10 to 1.14. + +This fixes a memory leak when DBM filters are used. + +=item * + +L<Hash::Util> has been upgraded from 0.07 to 0.11. + +L<Hash::Util> no longer emits spurious "uninitialized" warnings when +recursively locking hashes that have undefined values [perl #74280]. + +=item * + +L<Hash::Util::FieldHash> has been upgraded from version 1.04 to 1.09. + +=item * + +L<I18N::Collate> has been upgraded from version 1.01 to 1.02. + +=item * + +L<I18N::Langinfo> has been upgraded from version 0.03 to 0.08. + +langinfo() now defaults to using C<$_> if there is no argument given, just +as the documentation has always claimed. + +=item * + +L<I18N::LangTags> has been upgraded from version 0.35 to 0.35_01. + +=item * + +L<if> has been upgraded from version 0.05 to 0.0601. + +=item * + +L<IO> has been upgraded from version 1.25_02 to 1.25_04. + +This version of L<IO> includes a new L<IO::Select>, which now allows L<IO::Handle> +objects (and objects in derived classes) to be removed from an L<IO::Select> set +even if the underlying file descriptor is closed or invalid. + +=item * + +L<IPC::Cmd> has been upgraded from version 0.54 to 0.70. + +Resolves an issue with splitting Win32 command lines. An argument +consisting of the single character "0" used to be omitted (CPAN RT #62961). + +=item * + +L<IPC::Open3> has been upgraded from 1.05 to 1.09. + +open3() now produces an error if the C<exec> call fails, allowing this +condition to be distinguished from a child process that exited with a +non-zero status [perl #72016]. + +The internal xclose() routine now knows how to handle file descriptors as +documented, so duplicating C<STDIN> in a child process using its file +descriptor now works [perl #76474]. + +=item * + +L<IPC::SysV> has been upgraded from version 2.01 to 2.03. + +=item * + +L<lib> has been upgraded from version 0.62 to 0.63. + +=item * + +L<Locale::Maketext> has been upgraded from version 1.14 to 1.19. + +L<Locale::Maketext> now supports external caches. + +This upgrade also fixes an infinite loop in +C<Locale::Maketext::Guts::_compile()> when +working with tainted values (CPAN RT #40727). + +C<< ->maketext >> calls now back up and restore C<$@> so error +messages are not suppressed (CPAN RT #34182). + +=item * + +L<Log::Message> has been upgraded from version 0.02 to 0.04. + +=item * + +L<Log::Message::Simple> has been upgraded from version 0.06 to 0.08. + +=item * + +L<Math::BigInt> has been upgraded from version 1.89_01 to 1.994. + +This fixes, among other things, incorrect results when computing binomial +coefficients [perl #77640]. + +It also prevents C<sqrt($int)> from crashing under C<use bigrat>. +[perl #73534]. + +=item * + +L<Math::BigInt::FastCalc> has been upgraded from version 0.19 to 0.28. + +=item * + +L<Math::BigRat> has been upgraded from version 0.24 to 0.26_02. + +=item * + +L<Memoize> has been upgraded from version 1.01_03 to 1.02. + +=item * + +L<MIME::Base64> has been upgraded from 3.08 to 3.13. + +Includes new functions to calculate the length of encoded and decoded +base64 strings. + +Now provides encode_base64url() and decode_base64url() functions to process +the base64 scheme for "URL applications". + +=item * + +L<Module::Build> has been upgraded from version 0.3603 to 0.3800. + +A notable change is the deprecation of several modules. +L<Module::Build::Version> has been deprecated and L<Module::Build> now +relies on the L<version> pragma directly. L<Module::Build::ModuleInfo> has +been deprecated in favor of a standalone copy called L<Module::Metadata>. +L<Module::Build::YAML> has been deprecated in favor of L<CPAN::Meta::YAML>. + +L<Module::Build> now also generates F<META.json> and F<MYMETA.json> files +in accordance with version 2 of the CPAN distribution metadata specification, +L<CPAN::Meta::Spec>. The older format F<META.yml> and F<MYMETA.yml> files are +still generated. + +=item * + +L<Module::CoreList> has been upgraded from version 2.29 to 2.47. + +Besides listing the updated core modules of this release, it also stops listing +the C<Filespec> module. That module never existed in core. The scripts +generating L<Module::CoreList> confused it with L<VMS::Filespec>, which actually +is a core module as of Perl 5.8.7. + +=item * + +L<Module::Load> has been upgraded from version 0.16 to 0.18. + +=item * + +L<Module::Load::Conditional> has been upgraded from version 0.34 to 0.44. + +=item * + +The L<mro> pragma has been upgraded from version 1.02 to 1.07. + +=item * + +L<NDBM_File> has been upgraded from version 1.08 to 1.12. + +This fixes a memory leak when DBM filters are used. + +=item * + +L<Net::Ping> has been upgraded from version 2.36 to 2.38. + +=item * + +L<NEXT> has been upgraded from version 0.64 to 0.65. + +=item * + +L<Object::Accessor> has been upgraded from version 0.36 to 0.38. + +=item * + +L<ODBM_File> has been upgraded from version 1.07 to 1.10. + +This fixes a memory leak when DBM filters are used. + +=item * + +L<Opcode> has been upgraded from version 1.15 to 1.18. + +=item * + +The L<overload> pragma has been upgraded from 1.10 to 1.13. + +C<overload::Method> can now handle subroutines that are themselves blessed +into overloaded classes [perl #71998]. + +The documentation has greatly improved. See L</Documentation> below. + +=item * + +L<Params::Check> has been upgraded from version 0.26 to 0.28. + +=item * + +The L<parent> pragma has been upgraded from version 0.223 to 0.225. + +=item * + +L<Parse::CPAN::Meta> has been upgraded from version 1.40 to 1.4401. + +The latest Parse::CPAN::Meta can now read YAML and JSON files using +L<CPAN::Meta::YAML> and L<JSON::PP>, which are now part of the Perl core. + +=item * + +L<PerlIO::encoding> has been upgraded from version 0.12 to 0.14. + +=item * + +L<PerlIO::scalar> has been upgraded from 0.07 to 0.11. + +A read() after a seek() beyond the end of the string no longer thinks it +has data to read [perl #78716]. + +=item * + +L<PerlIO::via> has been upgraded from version 0.09 to 0.11. + +=item * + +L<Pod::Html> has been upgraded from version 1.09 to 1.11. + +=item * + +L<Pod::LaTeX> has been upgraded from version 0.58 to 0.59. + +=item * + +L<Pod::Perldoc> has been upgraded from version 3.15_02 to 3.15_03. + +=item * + +L<Pod::Simple> has been upgraded from version 3.13 to 3.16. + +=item * + +L<POSIX> has been upgraded from 1.19 to 1.24. + +It now includes constants for POSIX signal constants. + +=item * + +The L<re> pragma has been upgraded from version 0.11 to 0.18. + +The C<use re '/flags'> subpragma is new. + +The regmust() function used to crash when called on a regular expression +belonging to a pluggable engine. Now it croaks instead. + +regmust() no longer leaks memory. + +=item * + +L<Safe> has been upgraded from version 2.25 to 2.29. + +Coderefs returned by reval() and rdo() are now wrapped via +wrap_code_refs() (5.12.1). + +This fixes a possible infinite loop when looking for coderefs. + +It adds several C<version::vxs::*> routines to the default share. + +=item * + +L<SDBM_File> has been upgraded from version 1.06 to 1.09. + +=item * + +L<SelfLoader> has been upgraded from 1.17 to 1.18. + +It now works in taint mode [perl #72062]. + +=item * + +The L<sigtrap> pragma has been upgraded from version 1.04 to 1.05. + +It no longer tries to modify read-only arguments when generating a +backtrace [perl #72340]. + +=item * + +L<Socket> has been upgraded from version 1.87 to 1.94. + +See L</Improved IPv6 support> above. + +=item * + +L<Storable> has been upgraded from version 2.22 to 2.27. + +Includes performance improvement for overloaded classes. + +This adds support for serialising code references that contain UTF-8 strings +correctly. The L<Storable> minor version +number changed as a result, meaning that +L<Storable> users who set C<$Storable::accept_future_minor> to a C<FALSE> value +will see errors (see L<Storable/FORWARD COMPATIBILITY> for more details). + +Freezing no longer gets confused if the Perl stack gets reallocated +during freezing [perl #80074]. + +=item * + +L<Sys::Hostname> has been upgraded from version 1.11 to 1.16. + +=item * + +L<Term::ANSIColor> has been upgraded from version 2.02 to 3.00. + +=item * + +L<Term::UI> has been upgraded from version 0.20 to 0.26. + +=item * + +L<Test::Harness> has been upgraded from version 3.17 to 3.23. + +=item * + +L<Test::Simple> has been upgraded from version 0.94 to 0.98. + +Among many other things, subtests without a C<plan> or C<no_plan> now have an +implicit done_testing() added to them. + +=item * + +L<Thread::Semaphore> has been upgraded from version 2.09 to 2.12. + +It provides two new methods that give more control over the decrementing of +semaphores: C<down_nb> and C<down_force>. + +=item * + +L<Thread::Queue> has been upgraded from version 2.11 to 2.12. + +=item * + +The L<threads> pragma has been upgraded from version 1.75 to 1.83. + +=item * + +The L<threads::shared> pragma has been upgraded from version 1.32 to 1.37. + +=item * + +L<Tie::Hash> has been upgraded from version 1.03 to 1.04. + +Calling C<< Tie::Hash->TIEHASH() >> used to loop forever. Now it C<croak>s. + +=item * + +L<Tie::Hash::NamedCapture> has been upgraded from version 0.06 to 0.08. + +=item * + +L<Tie::RefHash> has been upgraded from version 1.38 to 1.39. + +=item * + +L<Time::HiRes> has been upgraded from version 1.9719 to 1.9721_01. + +=item * + +L<Time::Local> has been upgraded from version 1.1901_01 to 1.2000. + +=item * + +L<Time::Piece> has been upgraded from version 1.15_01 to 1.20_01. + +=item * + +L<Unicode::Collate> has been upgraded from version 0.52_01 to 0.73. + +L<Unicode::Collate> has been updated to use Unicode 6.0.0. + +L<Unicode::Collate::Locale> now supports a plethora of new locales: I<ar, be, +bg, de__phonebook, hu, hy, kk, mk, nso, om, tn, vi, hr, ig, ja, ko, ru, sq, +se, sr, to, uk, zh, zh__big5han, zh__gb2312han, zh__pinyin>, and I<zh__stroke>. + +The following modules have been added: + +L<Unicode::Collate::CJK::Big5> for C<zh__big5han> which makes +tailoring of CJK Unified Ideographs in the order of CLDR's big5han ordering. + +L<Unicode::Collate::CJK::GB2312> for C<zh__gb2312han> which makes +tailoring of CJK Unified Ideographs in the order of CLDR's gb2312han ordering. + +L<Unicode::Collate::CJK::JISX0208> which makes tailoring of 6355 kanji +(CJK Unified Ideographs) in the JIS X 0208 order. + +L<Unicode::Collate::CJK::Korean> which makes tailoring of CJK Unified Ideographs +in the order of CLDR's Korean ordering. + +L<Unicode::Collate::CJK::Pinyin> for C<zh__pinyin> which makes +tailoring of CJK Unified Ideographs in the order of CLDR's pinyin ordering. + +L<Unicode::Collate::CJK::Stroke> for C<zh__stroke> which makes +tailoring of CJK Unified Ideographs in the order of CLDR's stroke ordering. + +This also sees the switch from using the pure-Perl version of this +module to the XS version. + +=item * + +L<Unicode::Normalize> has been upgraded from version 1.03 to 1.10. + +=item * + +L<Unicode::UCD> has been upgraded from version 0.27 to 0.32. + +A new function, Unicode::UCD::num(), has been added. This function +returns the numeric value of the string passed it or C<undef> if the string +in its entirety has no "safe" numeric value. (For more detail, and for the +definition of "safe", see L<Unicode::UCD/num>.) + +This upgrade also includes several bug fixes: + +=over 4 + +=item charinfo() + +=over 4 + +=item * + +It is now updated to Unicode Version 6.0.0 with I<Corrigendum #8>, +excepting that, just as with Perl 5.14, the code point at U+1F514 has no name. + +=item * + +Hangul syllable code points have the correct names, and their +decompositions are always output without requiring L<Lingua::KO::Hangul::Util> +to be installed. + +=item * + +CJK (Chinese-Japanese-Korean) code points U+2A700 to U+2B734 +and U+2B740 to U+2B81D are now properly handled. + +=item * + +Numeric values are now output for those CJK code points that have them. + +=item * + +Names output for code points with multiple aliases are now the +corrected ones. + +=back + +=item charscript() + +This now correctly returns "Unknown" instead of C<undef> for the script +of a code point that hasn't been assigned another one. + +=item charblock() + +This now correctly returns "No_Block" instead of C<undef> for the block +of a code point that hasn't been assigned to another one. + +=back + +=item * + +The L<version> pragma has been upgraded from 0.82 to 0.88. + +Because of a bug, now fixed, the is_strict() and is_lax() functions did not +work when exported (5.12.1). + +=item * + +The L<warnings> pragma has been upgraded from version 1.09 to 1.12. + +Calling C<use warnings> without arguments is now significantly more efficient. + +=item * + +The L<warnings::register> pragma has been upgraded from version 1.01 to 1.02. + +It is now possible to register warning categories other than the names of +packages using L<warnings::register>. See L<perllexwarn(1)> for more information. + +=item * + +L<XSLoader> has been upgraded from version 0.10 to 0.13. + +=item * + +L<VMS::DCLsym> has been upgraded from version 1.03 to 1.05. + +Two bugs have been fixed [perl #84086]: + +The symbol table name was lost when tying a hash, due to a thinko in +C<TIEHASH>. The result was that all tied hashes interacted with the +local symbol table. + +Unless a symbol table name had been explicitly specified in the call +to the constructor, querying the special key C<:LOCAL> failed to +identify objects connected to the local symbol table. + +=item * + +The L<Win32> module has been upgraded from version 0.39 to 0.44. + +This release has several new functions: Win32::GetSystemMetrics(), +Win32::GetProductInfo(), Win32::GetOSDisplayName(). + +The names returned by Win32::GetOSName() and Win32::GetOSDisplayName() +have been corrected. + +=item * + +L<XS::Typemap> has been upgraded from version 0.03 to 0.05. + +=back + +=head2 Removed Modules and Pragmata + +As promised in Perl 5.12.0's release notes, the following modules have +been removed from the core distribution, and if needed should be installed +from CPAN instead. + +=over + +=item * + +L<Class::ISA> has been removed from the Perl core. Prior version was 0.36. + +=item * + +L<Pod::Plainer> has been removed from the Perl core. Prior version was 1.02. + +=item * + +L<Switch> has been removed from the Perl core. Prior version was 2.16. + +=back + +The removal of L<Shell> has been deferred until after 5.14, as the +implementation of L<Shell> shipped with 5.12.0 did not correctly issue the +warning that it was to be removed from core. + +=head1 Documentation + +=head2 New Documentation + +=head3 L<perlgpl> + +L<perlgpl> has been updated to contain GPL version 1, as is included in the +F<README> distributed with Perl (5.12.1). + +=head3 Perl 5.12.x delta files + +The perldelta files for Perl 5.12.1 to 5.12.3 have been added from the +maintenance branch: L<perl5121delta>, L<perl5122delta>, L<perl5123delta>. + +=head3 L<perlpodstyle> + +New style guide for POD documentation, +split mostly from the NOTES section of the L<pod2man(1)> manpage. + +=head3 L<perlsource>, L<perlinterp>, L<perlhacktut>, and L<perlhacktips> + +See L</perlhack and perlrepository revamp>, below. + +=head2 Changes to Existing Documentation + +=head3 L<perlmodlib> is now complete + +The L<perlmodlib> manpage that came with Perl 5.12.0 was missing several +modules due to a bug in the script that generates the list. This has been +fixed [perl #74332] (5.12.1). + +=head3 Replace incorrect tr/// table in L<perlebcdic> + +L<perlebcdic> contains a helpful table to use in C<tr///> to convert +between EBCDIC and Latin1/ASCII. The table was the inverse of the one +it describes, though the code that used the table worked correctly for +the specific example given. + +The table has been corrected and the sample code changed to correspond. + +The table has also been changed to hex from octal, and the recipes in the +pod have been altered to print out leading zeros to make all values +the same length. + +=head3 Tricks for user-defined casing + +L<perlunicode> now contains an explanation of how to override, mangle +and otherwise tweak the way Perl handles upper-, lower- and other-case +conversions on Unicode data, and how to provide scoped changes to alter +one's own code's behaviour without stomping on anybody else's. + +=head3 INSTALL explicitly states that Perl requires a C89 compiler + +This was already true, but it's now Officially Stated For The Record +(5.12.2). + +=head3 Explanation of C<\xI<HH>> and C<\oI<OOO>> escapes + +L<perlop> has been updated with more detailed explanation of these two +character escapes. + +=head3 B<-0I<NNN>> switch + +In L<perlrun>, the behaviour of the B<-0NNN> switch for B<-0400> or higher +has been clarified (5.12.2). + +=head3 Maintenance policy + +L<perlpolicy> now contains the policy on what patches are acceptable for +maintenance branches (5.12.1). + +=head3 Deprecation policy + +L<perlpolicy> now contains the policy on compatibility and deprecation +along with definitions of terms like "deprecation" (5.12.2). + +=head3 New descriptions in L<perldiag> + +The following existing diagnostics are now documented: + +=over 4 + +=item * + +L<Ambiguous use of %c resolved as operator %c|perldiag/"Ambiguous use of %c resolved as operator %c"> + +=item * + +L<Ambiguous use of %c{%s} resolved to %c%s|perldiag/"Ambiguous use of %c{%s} resolved to %c%s"> + +=item * + +L<Ambiguous use of %c{%s[...]} resolved to %c%s[...]|perldiag/"Ambiguous use of %c{%s[...]} resolved to %c%s[...]"> + +=item * + +L<Ambiguous use of %c{%s{...}} resolved to %c%s{...}|perldiag/"Ambiguous use of %c{%s{...}} resolved to %c%s{...}"> + +=item * + +L<Ambiguous use of -%s resolved as -&%s()|perldiag/"Ambiguous use of -%s resolved as -&%s()"> + +=item * + +L<Invalid strict version format (%s)|perldiag/"Invalid strict version format (%s)"> + +=item * + +L<Invalid version format (%s)|perldiag/"Invalid version format (%s)"> + +=item * + +L<Invalid version object|perldiag/"Invalid version object"> + +=back + +=head3 L<perlbook> + +L<perlbook> has been expanded to cover many more popular books. + +=head3 C<SvTRUE> macro + +The documentation for the C<SvTRUE> macro in +L<perlapi> was simply wrong in stating that +get-magic is not processed. It has been corrected. + +=head3 op manipulation functions + +Several API functions that process optrees have been newly documented. + +=head3 L<perlvar> revamp + +L<perlvar> reorders the variables and groups them by topic. Each variable +introduced after Perl 5.000 notes the first version in which it is +available. L<perlvar> also has a new section for deprecated variables to +note when they were removed. + +=head3 Array and hash slices in scalar context + +These are now documented in L<perldata>. + +=head3 C<use locale> and formats + +L<perlform> and L<perllocale> have been corrected to state that +C<use locale> affects formats. + +=head3 L<overload> + +L<overload>'s documentation has practically undergone a rewrite. It +is now much more straightforward and clear. + +=head3 perlhack and perlrepository revamp + +The L<perlhack> document is now much shorter, and focuses on the Perl 5 +development process and submitting patches to Perl. The technical content +has been moved to several new documents, L<perlsource>, L<perlinterp>, +L<perlhacktut>, and L<perlhacktips>. This technical content has +been only lightly edited. + +The perlrepository document has been renamed to L<perlgit>. This new +document is just a how-to on using git with the Perl source code. +Any other content that used to be in perlrepository has been moved +to L<perlhack>. + +=head3 Time::Piece examples + +Examples in L<perlfaq4> have been updated to show the use of +L<Time::Piece>. + +=head1 Diagnostics + +The following additions or changes have been made to diagnostic output, +including warnings and fatal error messages. For the complete list of +diagnostic messages, see L<perldiag>. + +=head2 New Diagnostics + +=head3 New Errors + +=over + +=item Closure prototype called + +This error occurs when a subroutine reference passed to an attribute +handler is called, if the subroutine is a closure [perl #68560]. + +=item Insecure user-defined property %s + +Perl detected tainted data when trying to compile a regular +expression that contains a call to a user-defined character property +function, meaning C<\p{IsFoo}> or C<\p{InFoo}>. +See L<perlunicode/User-Defined Character Properties> and L<perlsec>. + +=item panic: gp_free failed to free glob pointer - something is repeatedly re-creating entries + +This new error is triggered if a destructor called on an object in a +typeglob that is being freed creates a new typeglob entry containing an +object with a destructor that creates a new entry containing an object etc. + +=item Parsing code internal error (%s) + +This new fatal error is produced when parsing +code supplied by an extension violates the +parser's API in a detectable way. + +=item refcnt: fd %d%s + +This new error only occurs if a internal consistency check fails when a +pipe is about to be closed. + +=item Regexp modifier "/%c" may not appear twice + +The regular expression pattern has one of the +mutually exclusive modifiers repeated. + +=item Regexp modifiers "/%c" and "/%c" are mutually exclusive + +The regular expression pattern has more than one of the mutually +exclusive modifiers. + +=item Using !~ with %s doesn't make sense + +This error occurs when C<!~> is used with C<s///r> or C<y///r>. + +=back + +=head3 New Warnings + +=over + +=item "\b{" is deprecated; use "\b\{" instead + +=item "\B{" is deprecated; use "\B\{" instead + +Use of an unescaped "{" immediately following a C<\b> or C<\B> is now +deprecated in order to reserve its use for Perl itself in a future release. + +=item Operation "%s" returns its argument for ... + +Performing an operation requiring Unicode semantics (such as case-folding) +on a Unicode surrogate or a non-Unicode character now triggers this +warning. + +=item Use of qw(...) as parentheses is deprecated + +See L</"Use of qw(...) as parentheses">, above, for details. + +=back + +=head2 Changes to Existing Diagnostics + +=over 4 + +=item * + +The "Variable $foo is not imported" warning that precedes a +C<strict 'vars'> error has now been assigned the "misc" category, so that +C<no warnings> will suppress it [perl #73712]. + +=item * + +warn() and die() now produce "Wide character" warnings when fed a +character outside the byte range if C<STDERR> is a byte-sized handle. + +=item * + +The "Layer does not match this perl" error message has been replaced with +these more helpful messages [perl #73754]: + +=over 4 + +=item * + +PerlIO layer function table size (%d) does not match size expected by this +perl (%d) + +=item * + +PerlIO layer instance size (%d) does not match size expected by this perl +(%d) + +=back + +=item * + +The "Found = in conditional" warning that is emitted when a constant is +assigned to a variable in a condition is now withheld if the constant is +actually a subroutine or one generated by C<use constant>, since the value +of the constant may not be known at the time the program is written +[perl #77762]. + +=item * + +Previously, if none of the gethostbyaddr(), gethostbyname() and +gethostent() functions were implemented on a given platform, they would +all die with the message "Unsupported socket function 'gethostent' called", +with analogous messages for getnet*() and getserv*(). This has been +corrected. + +=item * + +The warning message about unrecognized regular expression escapes passed +through has been changed to include any literal "{" following the +two-character escape. For example, "\q{" is now emitted instead of "\q". + +=back + +=head1 Utility Changes + +=head3 L<perlbug(1)> + +=over 4 + +=item * + +L<perlbug> now looks in the EMAIL environment variable for a return address +if the REPLY-TO and REPLYTO variables are empty. + +=item * + +L<perlbug> did not previously generate a "From:" header, potentially +resulting in dropped mail; it now includes that header. + +=item * + +The user's address is now used as the Return-Path. + +Many systems these days don't have a valid Internet domain name, and +perlbug@perl.org does not accept email with a return-path that does +not resolve. So the user's address is now passed to sendmail so it's +less likely to get stuck in a mail queue somewhere [perl #82996]. + +=item * + +L<perlbug> now always gives the reporter a chance to change the email +address it guesses for them (5.12.2). + +=item * + +L<perlbug> should no longer warn about uninitialized values when using the B<-d> +and B<-v> options (5.12.2). + +=back + +=head3 L<perl5db.pl> + +=over + +=item * + +The remote terminal works after forking and spawns new sessions, one +per forked process. + +=back + +=head3 L<ptargrep> + +=over 4 + +=item * + +L<ptargrep> is a new utility to apply pattern matching to the contents of +files in a tar archive. It comes with C<Archive::Tar>. + +=back + +=head1 Configuration and Compilation + +See also L</"Naming fixes in Policy_sh.SH may invalidate Policy.sh">, +above. + +=over 4 + +=item * + +CCINCDIR and CCLIBDIR for the mingw64 cross-compiler are now correctly +under F<$(CCHOME)\mingw\include> and F<\lib> rather than immediately below +F<$(CCHOME)>. + +This means the "incpath", "libpth", "ldflags", "lddlflags" and +"ldflags_nolargefiles" values in F<Config.pm> and F<Config_heavy.pl> are now +set correctly. + +=item * + +C<make test.valgrind> has been adjusted to account for F<cpan/dist/ext> +separation. + +=item * + +On compilers that support it, B<-Wwrite-strings> is now added to cflags by +default. + +=item * + +The L<Encode> module can now (once again) be included in a static Perl +build. The special-case handling for this situation got broken in Perl +5.11.0, and has now been repaired. + +=item * + +The previous default size of a PerlIO buffer (4096 bytes) has been increased +to the larger of 8192 bytes and your local BUFSIZ. Benchmarks show that doubling +this decade-old default increases read and write performance by around +25% to 50% when using the default layers of perlio on top of unix. To choose +a non-default size, such as to get back the old value or to obtain an even +larger value, configure with: + + ./Configure -Accflags=-DPERLIOBUF_DEFAULT_BUFSIZ=N + +where N is the desired size in bytes; it should probably be a multiple of +your page size. + +=item * + +An "incompatible operand types" error in ternary expressions when building +with C<clang> has been fixed (5.12.2). + +=item * + +Perl now skips setuid L<File::Copy> tests on partitions it detects mounted +as C<nosuid> (5.12.2). + +=back + +=head1 Platform Support + +=head2 New Platforms + +=over 4 + +=item AIX + +Perl now builds on AIX 4.2 (5.12.1). + +=back + +=head2 Discontinued Platforms + +=over 4 + +=item Apollo DomainOS + +The last vestiges of support for this platform have been excised from +the Perl distribution. It was officially discontinued in version 5.12.0. +It had not worked for years before that. + +=item MacOS Classic + +The last vestiges of support for this platform have been excised from the +Perl distribution. It was officially discontinued in an earlier version. + +=back + +=head2 Platform-Specific Notes + +=head3 AIX + +=over + +=item * + +F<README.aix> has been updated with information about the XL C/C++ V11 compiler +suite (5.12.2). + +=back + +=head3 ARM + +=over + +=item * + +The C<d_u32align> configuration probe on ARM has been fixed (5.12.2). + +=back + +=head3 Cygwin + +=over 4 + +=item * + +L<MakeMaker> has been updated to build manpages on cygwin. + +=item * + +Improved rebase behaviour + +If a DLL is updated on cygwin the old imagebase address is reused. +This solves most rebase errors, especially when updating on core DLL's. +See L<http://www.tishler.net/jason/software/rebase/rebase-2.4.2.README> +for more information. + +=item * + +Support for the standard cygwin dll prefix (needed for FFIs) + +=item * + +Updated build hints file + +=back + +=head3 FreeBSD 7 + +=over + +=item * + +FreeBSD 7 no longer contains F</usr/bin/objformat>. At build time, +Perl now skips the F<objformat> check for versions 7 and higher and +assumes ELF (5.12.1). + +=back + +=head3 HP-UX + +=over + +=item * + +Perl now allows B<-Duse64bitint> without promoting to C<use64bitall> on HP-UX +(5.12.1). + +=back + +=head3 IRIX + +=over + +=item * + +Conversion of strings to floating-point numbers is now more accurate on +IRIX systems [perl #32380]. + +=back + +=head3 Mac OS X + +=over + +=item * + +Early versions of Mac OS X (Darwin) had buggy implementations of the +setregid(), setreuid(), setrgid(,) and setruid() functions, so Perl +would pretend they did not exist. + +These functions are now recognised on Mac OS 10.5 (Leopard; Darwin 9) and +higher, as they have been fixed [perl #72990]. + +=back + +=head3 MirBSD + +=over + +=item * + +Previously if you built Perl with a shared F<libperl.so> on MirBSD (the +default config), it would work up to the installation; however, once +installed, it would be unable to find F<libperl>. Path handling is now +treated as in the other BSD dialects. + +=back + +=head3 NetBSD + +=over + +=item * + +The NetBSD hints file has been changed to make the system malloc the +default. + +=back + +=head3 OpenBSD + +=over + +=item * + +OpenBSD E<gt> 3.7 has a new malloc implementation which is I<mmap>-based, +and as such can release memory back to the OS; however, Perl's use of +this malloc causes a substantial slowdown, so we now default to using +Perl's malloc instead [perl #75742]. + +=back + +=head3 OpenVOS + +=over + +=item * + +Perl now builds again with OpenVOS (formerly known as Stratus VOS) +[perl #78132] (5.12.3). + +=back + +=head3 Solaris + +=over + +=item * + +DTrace is now supported on Solaris. There used to be build failures, but +these have been fixed [perl #73630] (5.12.3). + +=back + +=head3 VMS + +=over + +=item * + +Extension building on older (pre 7.3-2) VMS systems was broken because +configure.com hit the DCL symbol length limit of 1K. We now work within +this limit when assembling the list of extensions in the core build (5.12.1). + +=item * + +We fixed configuring and building Perl with B<-Uuseperlio> (5.12.1). + +=item * + +C<PerlIOUnix_open> now honours the default permissions on VMS. + +When C<perlio> became the default and C<unix> became the default bottom layer, +the most common path for creating files from Perl became C<PerlIOUnix_open>, +which has always explicitly used C<0666> as the permission mask. This prevents +inheriting permissions from RMS defaults and ACLs, so to avoid that problem, +we now pass C<0777> to open(). In theVMS CRTL, C<0777> has a special +meaning over and above intersecting with the current umask; specifically, it +allows Unix syscalls to preserve native default permissions (5.12.3). + +=item * + +The shortening of symbols longer than 31 characters in the core C sources +and in extensions is now by default done by the C compiler rather than by +xsubpp (which could only do so for generated symbols in XS code). You can +reenable xsubpp's symbol shortening by configuring with -Uuseshortenedsymbols, +but you'll have some work to do to get the core sources to compile. + +=item * + +Record-oriented files (record format variable or variable with fixed control) +opened for write by the C<perlio> layer will now be line-buffered to prevent the +introduction of spurious line breaks whenever the perlio buffer fills up. + +=item * + +F<git_version.h> is now installed on VMS. This was an oversight in v5.12.0 which +caused some extensions to fail to build (5.12.2). + +=item * + +Several memory leaks in L<stat()|perlfunc/"stat FILEHANDLE"> have been fixed (5.12.2). + +=item * + +A memory leak in Perl_rename() due to a double allocation has been +fixed (5.12.2). + +=item * + +A memory leak in vms_fid_to_name() (used by realpath() and +realname()> has been fixed (5.12.2). + +=back + +=head3 Windows + +See also L</"fork() emulation will not wait for signalled children"> and +L</"Perl source code is read in text mode on Windows">, above. + +=over 4 + +=item * + +Fixed build process for SDK2003SP1 compilers. + +=item * + +Compilation with Visual Studio 2010 is now supported. + +=item * + +When using old 32-bit compilers, the define C<_USE_32BIT_TIME_T> is now +set in C<$Config{ccflags}>. This improves portability when compiling +XS extensions using new compilers, but for a Perl compiled with old 32-bit +compilers. + +=item * + +C<$Config{gccversion}> is now set correctly when Perl is built using the +mingw64 compiler from L<http://mingw64.org> [perl #73754]. + +=item * + +When building Perl with the mingw64 x64 cross-compiler C<incpath>, +C<libpth>, C<ldflags>, C<lddlflags> and C<ldflags_nolargefiles> values +in F<Config.pm> and F<Config_heavy.pl> were not previously being set +correctly because, with that compiler, the include and lib directories +are not immediately below C<$(CCHOME)> (5.12.2). + +=item * + +The build process proceeds more smoothly with mingw and dmake when +F<C:\MSYS\bin> is in the PATH, due to a C<Cwd> fix. + +=item * + +Support for building with Visual C++ 2010 is now underway, but is not yet +complete. See F<README.win32> or L<perlwin32> for more details. + +=item * + +The option to use an externally-supplied crypt(), or to build with no +crypt() at all, has been removed. Perl supplies its own crypt() +implementation for Windows, and the political situation that required +this part of the distribution to sometimes be omitted is long gone. + +=back + +=head1 Internal Changes + +=head2 New APIs + +=head3 CLONE_PARAMS structure added to ease correct thread creation + +Modules that create threads should now create C<CLONE_PARAMS> structures +by calling the new function Perl_clone_params_new(), and free them with +Perl_clone_params_del(). This will ensure compatibility with any future +changes to the internals of the C<CLONE_PARAMS> structure layout, and that +it is correctly allocated and initialised. + +=head3 New parsing functions + +Several functions have been added for parsing Perl statements and +expressions. These functions are meant to be used by XS code invoked +during Perl parsing, in a recursive-descent manner, to allow modules to +augment the standard Perl syntax. + +=over + +=item * + +L<parse_stmtseq()|perlapi/parse_stmtseq> +parses a sequence of statements, up to closing brace or EOF. + +=item * + +L<parse_fullstmt()|perlapi/parse_fullstmt> +parses a complete Perl statement, including optional label. + +=item * + +L<parse_barestmt()|perlapi/parse_barestmt> +parses a statement without a label. + +=item * + +L<parse_block()|perlapi/parse_block> +parses a code block. + +=item * + +L<parse_label()|perlapi/parse_label> +parses a statement label, separate from statements. + +=item * + +L<C<parse_fullexpr()>|perlapi/parse_fullexpr>, +L<C<parse_listexpr()>|perlapi/parse_listexpr>, +L<C<parse_termexpr()>|perlapi/parse_termexpr>, and +L<C<parse_arithexpr()>|perlapi/parse_arithexpr> +parse expressions at various precedence levels. + +=back + +=head3 Hints hash API + +A new C API for introspecting the hinthash C<%^H> at runtime has been +added. See C<cop_hints_2hv>, C<cop_hints_fetchpvn>, C<cop_hints_fetchpvs>, +C<cop_hints_fetchsv>, and C<hv_copy_hints_hv> in L<perlapi> for details. + +A new, experimental API has been added for accessing the internal +structure that Perl uses for C<%^H>. See the functions beginning with +C<cophh_> in L<perlapi>. + +=head3 C interface to caller() + +The C<caller_cx> function has been added as an XSUB-writer's equivalent of +caller(). See L<perlapi> for details. + +=head3 Custom per-subroutine check hooks + +XS code in an extension module can now annotate a subroutine (whether +implemented in XS or in Perl) so that nominated XS code will be called +at compile time (specifically as part of op checking) to change the op +tree of that subroutine. The compile-time check function (supplied by +the extension module) can implement argument processing that can't be +expressed as a prototype, generate customised compile-time warnings, +perform constant folding for a pure function, inline a subroutine +consisting of sufficiently simple ops, replace the whole call with a +custom op, and so on. This was previously all possible by hooking the +C<entersub> op checker, but the new mechanism makes it easy to tie the +hook to a specific subroutine. See L<perlapi/cv_set_call_checker>. + +To help in writing custom check hooks, several subtasks within standard +C<entersub> op checking have been separated out and exposed in the API. + +=head3 Improved support for custom OPs + +Custom ops can now be registered with the new C<custom_op_register> C +function and the C<XOP> structure. This will make it easier to add new +properties of custom ops in the future. Two new properties have been added +already, C<xop_class> and C<xop_peep>. + +C<xop_class> is one of the OA_*OP constants. It allows L<B> and other +introspection mechanisms to work with custom ops +that aren't BASEOPs. C<xop_peep> is a pointer to +a function that will be called for ops of this +type from C<Perl_rpeep>. + +See L<perlguts/Custom Operators> and L<perlapi/Custom Operators> for more +detail. + +The old C<PL_custom_op_names>/C<PL_custom_op_descs> interface is still +supported but discouraged. + +=head3 Scope hooks + +It is now possible for XS code to hook into Perl's lexical scope +mechanism at compile time, using the new C<Perl_blockhook_register> +function. See L<perlguts/"Compile-time scope hooks">. + +=head3 The recursive part of the peephole optimizer is now hookable + +In addition to C<PL_peepp>, for hooking into the toplevel peephole optimizer, a +C<PL_rpeepp> is now available to hook into the optimizer recursing into +side-chains of the optree. + +=head3 New non-magical variants of existing functions + +The following functions/macros have been added to the API. The C<*_nomg> +macros are equivalent to their non-C<_nomg> variants, except that they ignore +get-magic. Those ending in C<_flags> allow one to specify whether +get-magic is processed. + + sv_2bool_flags + SvTRUE_nomg + sv_2nv_flags + SvNV_nomg + sv_cmp_flags + sv_cmp_locale_flags + sv_eq_flags + sv_collxfrm_flags + +In some of these cases, the non-C<_flags> functions have +been replaced with wrappers around the new functions. + +=head3 pv/pvs/sv versions of existing functions + +Many functions ending with pvn now have equivalent C<pv/pvs/sv> versions. + +=head3 List op-building functions + +List op-building functions have been added to the +API. See L<op_append_elem|perlapi/op_append_elem>, +L<op_append_list|perlapi/op_append_list>, and +L<op_prepend_elem|perlapi/op_prepend_elem> in L<perlapi>. + +=head3 C<LINKLIST> + +The L<LINKLIST|perlapi/LINKLIST> macro, part of op building that +constructs the execution-order op chain, has been added to the API. + +=head3 Localisation functions + +The C<save_freeop>, C<save_op>, C<save_pushi32ptr> and C<save_pushptrptr> +functions have been added to the API. + +=head3 Stash names + +A stash can now have a list of effective names in addition to its usual +name. The first effective name can be accessed via the C<HvENAME> macro, +which is now the recommended name to use in MRO linearisations (C<HvNAME> +being a fallback if there is no C<HvENAME>). + +These names are added and deleted via C<hv_ename_add> and +C<hv_ename_delete>. These two functions are I<not> part of the API. + +=head3 New functions for finding and removing magic + +The L<C<mg_findext()>|perlapi/mg_findext> and +L<C<sv_unmagicext()>|perlapi/sv_unmagicext> +functions have been added to the API. +They allow extension authors to find and remove magic attached to +scalars based on both the magic type and the magic virtual table, similar to how +sv_magicext() attaches magic of a certain type and with a given virtual table +to a scalar. This eliminates the need for extensions to walk the list of +C<MAGIC> pointers of an C<SV> to find the magic that belongs to them. + +=head3 C<find_rundefsv> + +This function returns the SV representing C<$_>, whether it's lexical +or dynamic. + +=head3 C<Perl_croak_no_modify> + +Perl_croak_no_modify() is short-hand for +C<Perl_croak("%s", PL_no_modify)>. + +=head3 C<PERL_STATIC_INLINE> define + +The C<PERL_STATIC_INLINE> define has been added to provide the best-guess +incantation to use for static inline functions, if the C compiler supports +C99-style static inline. If it doesn't, it'll give a plain C<static>. + +C<HAS_STATIC_INLINE> can be used to check if the compiler actually supports +inline functions. + +=head3 New C<pv_escape> option for hexadecimal escapes + +A new option, C<PERL_PV_ESCAPE_NONASCII>, has been added to C<pv_escape> to +dump all characters above ASCII in hexadecimal. Before, one could get all +characters as hexadecimal or the Latin1 non-ASCII as octal. + +=head3 C<lex_start> + +C<lex_start> has been added to the API, but is considered experimental. + +=head3 op_scope() and op_lvalue() + +The op_scope() and op_lvalue() functions have been added to the API, +but are considered experimental. + +=head2 C API Changes + +=head3 C<PERL_POLLUTE> has been removed + +The option to define C<PERL_POLLUTE> to expose older 5.005 symbols for +backwards compatibility has been removed. Its use was always discouraged, +and MakeMaker contains a more specific escape hatch: + + perl Makefile.PL POLLUTE=1 + +This can be used for modules that have not been upgraded to 5.6 naming +conventions (and really should be completely obsolete by now). + +=head3 Check API compatibility when loading XS modules + +When Perl's API changes in incompatible ways (which usually happens between +major releases), XS modules compiled for previous versions of Perl will no +longer work. They need to be recompiled against the new Perl. + +The C<XS_APIVERSION_BOOTCHECK> macro has been added to ensure that modules +are recompiled and to prevent users from accidentally loading modules +compiled for old perls into newer perls. That macro, which is called when +loading every newly compiled extension, compares the API version of the +running perl with the version a module has been compiled for and raises an +exception if they don't match. + +=head3 Perl_fetch_cop_label + +The first argument of the C API function C<Perl_fetch_cop_label> has changed +from C<struct refcounted_he *> to C<COP *>, to insulate the user from +implementation details. + +This API function was marked as "may change", and likely isn't in use outside +the core. (Neither an unpacked CPAN nor Google's codesearch finds any other +references to it.) + +=head3 GvCV() and GvGP() are no longer lvalues + +The new GvCV_set() and GvGP_set() macros are now provided to replace +assignment to those two macros. + +This allows a future commit to eliminate some backref magic between GV +and CVs, which will require complete control over assignment to the +C<gp_cv> slot. + +=head3 CvGV() is no longer an lvalue + +Under some circumstances, the CvGV() field of a CV is now +reference-counted. To ensure consistent behaviour, direct assignment to +it, for example C<CvGV(cv) = gv> is now a compile-time error. A new macro, +C<CvGV_set(cv,gv)> has been introduced to run this operation +safely. Note that modification of this field is not part of the public +API, regardless of this new macro (and despite its being listed in this section). + +=head3 CvSTASH() is no longer an lvalue + +The CvSTASH() macro can now only be used as an rvalue. CvSTASH_set() +has been added to replace assignment to CvSTASH(). This is to ensure +that backreferences are handled properly. These macros are not part of the +API. + +=head3 Calling conventions for C<newFOROP> and C<newWHILEOP> + +The way the parser handles labels has been cleaned up and refactored. As a +result, the newFOROP() constructor function no longer takes a parameter +stating what label is to go in the state op. + +The newWHILEOP() and newFOROP() functions no longer accept a line +number as a parameter. + +=head3 Flags passed to C<uvuni_to_utf8_flags> and C<utf8n_to_uvuni> + +Some of the flags parameters to uvuni_to_utf8_flags() and +utf8n_to_uvuni() have changed. This is a result of Perl's now allowing +internal storage and manipulation of code points that are problematic +in some situations. Hence, the default actions for these functions has +been complemented to allow these code points. The new flags are +documented in L<perlapi>. Code that requires the problematic code +points to be rejected needs to change to use the new flags. Some flag +names are retained for backward source compatibility, though they do +nothing, as they are now the default. However the flags +C<UNICODE_ALLOW_FDD0>, C<UNICODE_ALLOW_FFFF>, C<UNICODE_ILLEGAL>, and +C<UNICODE_IS_ILLEGAL> have been removed, as they stem from a +fundamentally broken model of how the Unicode non-character code points +should be handled, which is now described in +L<perlunicode/Non-character code points>. See also the Unicode section +under L</Selected Bug Fixes>. + +=head2 Deprecated C APIs + +=over + +=item C<Perl_ptr_table_clear> + +C<Perl_ptr_table_clear> is no longer part of Perl's public API. Calling it +now generates a deprecation warning, and it will be removed in a future +release. + +=item C<sv_compile_2op> + +The sv_compile_2op() API function is now deprecated. Searches suggest +that nothing on CPAN is using it, so this should have zero impact. + +It attempted to provide an API to compile code down to an optree, but failed +to bind correctly to lexicals in the enclosing scope. It's not possible to +fix this problem within the constraints of its parameters and return value. + +=item C<find_rundefsvoffset> + +The C<find_rundefsvoffset> function has been deprecated. It appeared that +its design was insufficient for reliably getting the lexical C<$_> at +run-time. + +Use the new C<find_rundefsv> function or the C<UNDERBAR> macro +instead. They directly return the right SV +representing C<$_>, whether it's +lexical or dynamic. + +=item C<CALL_FPTR> and C<CPERLscope> + +Those are left from an old implementation of C<MULTIPLICITY> using C++ objects, +which was removed in Perl 5.8. Nowadays these macros do exactly nothing, so +they shouldn't be used anymore. + +For compatibility, they are still defined for external C<XS> code. Only +extensions defining C<PERL_CORE> must be updated now. + +=back + +=head2 Other Internal Changes + +=head3 Stack unwinding + +The protocol for unwinding the C stack at the last stage of a C<die> +has changed how it identifies the target stack frame. This now uses +a separate variable C<PL_restartjmpenv>, where previously it relied on +the C<blk_eval.cur_top_env> pointer in the C<eval> context frame that +has nominally just been discarded. This change means that code running +during various stages of Perl-level unwinding no longer needs to take +care to avoid destroying the ghost frame. + +=head3 Scope stack entries + +The format of entries on the scope stack has been changed, resulting in a +reduction of memory usage of about 10%. In particular, the memory used by +the scope stack to record each active lexical variable has been halved. + +=head3 Memory allocation for pointer tables + +Memory allocation for pointer tables has been changed. Previously +C<Perl_ptr_table_store> allocated memory from the same arena system as +C<SV> bodies and C<HE>s, with freed memory remaining bound to those arenas +until interpreter exit. Now it allocates memory from arenas private to the +specific pointer table, and that memory is returned to the system when +C<Perl_ptr_table_free> is called. Additionally, allocation and release are +both less CPU intensive. + +=head3 C<UNDERBAR> + +The C<UNDERBAR> macro now calls C<find_rundefsv>. C<dUNDERBAR> is now a +noop but should still be used to ensure past and future compatibility. + +=head3 String comparison routines renamed + +The C<ibcmp_*> functions have been renamed and are now called C<foldEQ>, +C<foldEQ_locale>, and C<foldEQ_utf8>. The old names are still available as +macros. + +=head3 C<chop> and C<chomp> implementations merged + +The opcode bodies for C<chop> and C<chomp> and for C<schop> and C<schomp> +have been merged. The implementation functions Perl_do_chop() and +Perl_do_chomp(), never part of the public API, have been merged and +moved to a static function in F<pp.c>. This shrinks the Perl binary +slightly, and should not affect any code outside the core (unless it is +relying on the order of side-effects when C<chomp> is passed a I<list> of +values). + +=head1 Selected Bug Fixes + +=head2 I/O + +=over 4 + +=item * + +Perl no longer produces this warning: + + $ perl -we 'open(my $f, ">", \my $x); binmode($f, "scalar")' + Use of uninitialized value in binmode at -e line 1. + +=item * + +Opening a glob reference via C<< open($fh, ">", \*glob) >> no longer +causes the glob to be corrupted when the filehandle is printed to. This would +cause Perl to crash whenever the glob's contents were accessed +[perl #77492]. + +=item * + +PerlIO no longer crashes when called recursively, such as from a signal +handler. Now it just leaks memory [perl #75556]. + +=item * + +Most I/O functions were not warning for unopened handles unless the +"closed" and "unopened" warnings categories were both enabled. Now only +C<use warnings 'unopened'> is necessary to trigger these warnings, as +had always been the intention. + +=item * + +There have been several fixes to PerlIO layers: + +When C<binmode(FH, ":crlf")> pushes the C<:crlf> layer on top of the stack, +it no longer enables crlf layers lower in the stack so as to avoid +unexpected results [perl #38456]. + +Opening a file in C<:raw> mode now does what it advertises to do (first +open the file, then C<binmode> it), instead of simply leaving off the top +layer [perl #80764]. + +The three layers C<:pop>, C<:utf8>, and C<:bytes> didn't allow stacking when +opening a file. For example +this: + + open(FH, ">:pop:perlio", "some.file") or die $!; + +would throw an "Invalid argument" error. This has been fixed in this +release [perl #82484]. + +=back + +=head2 Regular Expression Bug Fixes + +=over + +=item * + +The regular expression engine no longer loops when matching +C<"\N{LATIN SMALL LIGATURE FF}" =~ /f+/i> and similar expressions +[perl #72998] (5.12.1). + +=item * + +The trie runtime code should no longer allocate massive amounts of memory, +fixing #74484. + +=item * + +Syntax errors in C<< (?{...}) >> blocks no longer cause panic messages +[perl #2353]. + +=item * + +A pattern like C<(?:(o){2})?> no longer causes a "panic" error +[perl #39233]. + +=item * + +A fatal error in regular expressions containing C<(.*?)> when processing +UTF-8 data has been fixed [perl #75680] (5.12.2). + +=item * + +An erroneous regular expression engine optimisation that caused regex verbs like +C<*COMMIT> sometimes to be ignored has been removed. + +=item * + +The regular expression bracketed character class C<[\8\9]> was effectively the +same as C<[89\000]>, incorrectly matching a NULL character. It also gave +incorrect warnings that the C<8> and C<9> were ignored. Now C<[\8\9]> is the +same as C<[89]> and gives legitimate warnings that C<\8> and C<\9> are +unrecognized escape sequences, passed-through. + +=item * + +A regular expression match in the right-hand side of a global substitution +(C<s///g>) that is in the same scope will no longer cause match variables +to have the wrong values on subsequent iterations. This can happen when an +array or hash subscript is interpolated in the right-hand side, as in +C<s|(.)|@a{ print($1), /./ }|g> [perl #19078]. + +=item * + +Several cases in which characters in the Latin-1 non-ASCII range (0x80 to +0xFF) used not to match themselves, or used to match both a character class +and its complement, have been fixed. For instance, U+00E2 could match both +C<\w> and C<\W> [perl #78464] [perl #18281] [perl #60156]. + +=item * + +Matching a Unicode character against an alternation containing characters +that happened to match continuation bytes in the former's UTF8 +representation (like C<qq{\x{30ab}} =~ /\xab|\xa9/>) would cause erroneous +warnings [perl #70998]. + +=item * + +The trie optimisation was not taking empty groups into account, preventing +"foo" from matching C</\A(?:(?:)foo|bar|zot)\z/> [perl #78356]. + +=item * + +A pattern containing a C<+> inside a lookahead would sometimes cause an +incorrect match failure in a global match (for example, C</(?=(\S+))/g>) +[perl #68564]. + +=item * + +A regular expression optimisation would sometimes cause a match with a +C<{n,m}> quantifier to fail when it should have matched [perl #79152]. + +=item * + +Case-insensitive matching in regular expressions compiled under +C<use locale> now works much more sanely when the pattern or target +string is internally encoded in UTF8. Previously, under these +conditions the localeness was completely lost. Now, code points +above 255 are treated as Unicode, but code points between 0 and 255 +are treated using the current locale rules, regardless of whether +the pattern or the string is encoded in UTF8. The few case-insensitive +matches that cross the 255/256 boundary are not allowed. For +example, 0xFF does not caselessly match the character at 0x178, +LATIN CAPITAL LETTER Y WITH DIAERESIS, because 0xFF may not be LATIN +SMALL LETTER Y in the current locale, and Perl has no way of knowing +if that character even exists in the locale, much less what code +point it is. + +=item * + +The C<(?|...)> regular expression construct no longer crashes if the final +branch has more sets of capturing parentheses than any other branch. This +was fixed in Perl 5.10.1 for the case of a single branch, but that fix did +not take multiple branches into account [perl #84746]. + +=item * + +A bug has been fixed in the implementation of C<{...}> quantifiers in +regular expressions that prevented the code block in +C</((\w+)(?{ print $2 })){2}/> from seeing the C<$2> sometimes +[perl #84294]. + +=back + +=head2 Syntax/Parsing Bugs + +=over + +=item * + +C<when (scalar) {...}> no longer crashes, but produces a syntax error +[perl #74114] (5.12.1). + +=item * + +A label right before a string eval (C<foo: eval $string>) no longer causes +the label to be associated also with the first statement inside the eval +[perl #74290] (5.12.1). + +=item * + +The C<no 5.13.2> form of C<no> no longer tries to turn on features or +pragmata (like L<strict>) [perl #70075] (5.12.2). + +=item * + +C<BEGIN {require 5.12.0}> now behaves as documented, rather than behaving +identically to C<use 5.12.0>. Previously, C<require> in a C<BEGIN> block +was erroneously executing the C<use feature ':5.12.0'> and +C<use strict> behaviour, which only C<use> was documented to +provide [perl #69050]. + +=item * + +A regression introduced in Perl 5.12.0, making +C<< my $x = 3; $x = length(undef) >> result in C<$x> set to C<3> has been +fixed. C<$x> will now be C<undef> [perl #85508] (5.12.2). + +=item * + +When strict "refs" mode is off, C<%{...}> in rvalue context returns +C<undef> if its argument is undefined. An optimisation introduced in Perl +5.12.0 to make C<keys %{...}> faster when used as a boolean did not take +this into account, causing C<keys %{+undef}> (and C<keys %$foo> when +C<$foo> is undefined) to be an error, which it should be so in strict +mode only [perl #81750]. + +=item * + +Constant-folding used to cause + + $text =~ ( 1 ? /phoo/ : /bear/) + +to turn into + + $text =~ /phoo/ + +at compile time. Now it correctly matches against C<$_> [perl #20444]. + +=item * + +Parsing Perl code (either with string C<eval> or by loading modules) from +within a C<UNITCHECK> block no longer causes the interpreter to crash +[perl #70614]. + +=item * + +String C<eval>s no longer fail after 2 billion scopes have been +compiled [perl #83364]. + +=item * + +The parser no longer hangs when encountering certain Unicode characters, +such as U+387 [perl #74022]. + +=item * + +Defining a constant with the same name as one of Perl's special blocks +(like C<INIT>) stopped working in 5.12.0, but has now been fixed +[perl #78634]. + +=item * + +A reference to a literal value used as a hash key (C<$hash{\"foo"}>) used +to be stringified, even if the hash was tied [perl #79178]. + +=item * + +A closure containing an C<if> statement followed by a constant or variable +is no longer treated as a constant [perl #63540]. + +=item * + +C<state> can now be used with attributes. It +used to mean the same thing as +C<my> if any attributes were present [perl #68658]. + +=item * + +Expressions like C<< @$a > 3 >> no longer cause C<$a> to be mentioned in +the "Use of uninitialized value in numeric gt" warning when C<$a> is +undefined (since it is not part of the C<< > >> expression, but the operand +of the C<@>) [perl #72090]. + +=item * + +Accessing an element of a package array with a hard-coded number (as +opposed to an arbitrary expression) would crash if the array did not exist. +Usually the array would be autovivified during compilation, but typeglob +manipulation could remove it, as in these two cases which used to crash: + + *d = *a; print $d[0]; + undef *d; print $d[0]; + +=item * + +The B<-C> command-line option, when used on the shebang line, can now be +followed by other options [perl #72434]. + +=item * + +The C<B> module was returning C<B::OP>s instead of C<B::LOGOP>s for +C<entertry> [perl #80622]. This was due to a bug in the Perl core, +not in C<B> itself. + +=back + +=head2 Stashes, Globs and Method Lookup + +Perl 5.10.0 introduced a new internal mechanism for caching MROs (method +resolution orders, or lists of parent classes; aka "isa" caches) to make +method lookup faster (so C<@ISA> arrays would not have to be searched +repeatedly). Unfortunately, this brought with it quite a few bugs. Almost +all of these have been fixed now, along with a few MRO-related bugs that +existed before 5.10.0: + +=over + +=item * + +The following used to have erratic effects on method resolution, because +the "isa" caches were not reset or otherwise ended up listing the wrong +classes. These have been fixed. + +=over + +=item Aliasing packages by assigning to globs [perl #77358] + +=item Deleting packages by deleting their containing stash elements + +=item Undefining the glob containing a package (C<undef *Foo::>) + +=item Undefining an ISA glob (C<undef *Foo::ISA>) + +=item Deleting an ISA stash element (C<delete $Foo::{ISA}>) + +=item Sharing @ISA arrays between classes (via C<*Foo::ISA = \@Bar::ISA> or +C<*Foo::ISA = *Bar::ISA>) [perl #77238] + +=back + +C<undef *Foo::ISA> would even stop a new C<@Foo::ISA> array from updating +caches. + +=item * + +Typeglob assignments would crash if the glob's stash no longer existed, so +long as the glob assigned to were named C<ISA> or the glob on either side of +the assignment contained a subroutine. + +=item * + +C<PL_isarev>, which is accessible to Perl via C<mro::get_isarev> is now +updated properly when packages are deleted or removed from the C<@ISA> of +other classes. This allows many packages to be created and deleted without +causing a memory leak [perl #75176]. + +=back + +In addition, various other bugs related to typeglobs and stashes have been +fixed: + +=over + +=item * + +Some work has been done on the internal pointers that link between symbol +tables (stashes), typeglobs, and subroutines. This has the effect that +various edge cases related to deleting stashes or stash entries (for example, +<%FOO:: = ()>), and complex typeglob or code-reference aliasing, will no +longer crash the interpreter. + +=item * + +Assigning a reference to a glob copy now assigns to a glob slot instead of +overwriting the glob with a scalar [perl #1804] [perl #77508]. + +=item * + +A bug when replacing the glob of a loop variable within the loop has been fixed +[perl #21469]. This +means the following code will no longer crash: + + for $x (...) { + *x = *y; + } + +=item * + +Assigning a glob to a PVLV used to convert it to a plain string. Now it +works correctly, and a PVLV can hold a glob. This would happen when a +nonexistent hash or array element was passed to a subroutine: + + sub { $_[0] = *foo }->($hash{key}); + # $_[0] would have been the string "*main::foo" + +It also happened when a glob was assigned to, or returned from, an element +of a tied array or hash [perl #36051]. + +=item * + +When trying to report C<Use of uninitialized value $Foo::BAR>, crashes could +occur if the glob holding the global variable in question had been detached +from its original stash by, for example, C<delete $::{"Foo::"}>. This has +been fixed by disabling the reporting of variable names in those +cases. + +=item * + +During the restoration of a localised typeglob on scope exit, any +destructors called as a result would be able to see the typeglob in an +inconsistent state, containing freed entries, which could result in a +crash. This would affect code like this: + + local *@; + eval { die bless [] }; # puts an object in $@ + sub DESTROY { + local $@; # boom + } + +Now the glob entries are cleared before any destructors are called. This +also means that destructors can vivify entries in the glob. So Perl tries +again and, if the entries are re-created too many times, dies with a +"panic: gp_free ..." error message. + +=item * + +If a typeglob is freed while a subroutine attached to it is still +referenced elsewhere, the subroutine is renamed to C<__ANON__> in the same +package, unless the package has been undefined, in which case the C<__ANON__> +package is used. This could cause packages to be sometimes autovivified, +such as if the package had been deleted. Now this no longer occurs. +The C<__ANON__> package is also now used when the original package is +no longer attached to the symbol table. This avoids memory leaks in some +cases [perl #87664]. + +=item * + +Subroutines and package variables inside a package whose name ends with +C<::> can now be accessed with a fully qualified name. + +=back + +=head2 Unicode + +=over + +=item * + +What has become known as "the Unicode Bug" is almost completely resolved in +this release. Under C<use feature 'unicode_strings'> (which is +automatically selected by C<use 5.012> and above), the internal +storage format of a string no longer affects the external semantics. +[perl #58182]. + +There are two known exceptions: + +=over + +=item 1 + +The now-deprecated, user-defined case-changing +functions require utf8-encoded strings to operate. The CPAN module +L<Unicode::Casing> has been written to replace this feature without its +drawbacks, and the feature is scheduled to be removed in 5.16. + +=item 2 + +quotemeta() (and its in-line equivalent C<\Q>) can also give different +results depending on whether a string is encoded in UTF-8. See +L<perlunicode/The "Unicode Bug">. + +=back + +=item * + +Handling of Unicode non-character code points has changed. +Previously they were mostly considered illegal, except that in some +place only one of the 66 of them was known. The Unicode Standard +considers them all legal, but forbids their "open interchange". +This is part of the change to allow internal use of any code +point (see L</Core Enhancements>). Together, these changes resolve +[perl #38722], [perl #51918], [perl #51936], and [perl #63446]. + +=item * + +Case-insensitive C<"/i"> regular expression matching of Unicode +characters that match multiple characters now works much more as +intended. For example + + "\N{LATIN SMALL LIGATURE FFI}" =~ /ffi/ui + +and + + "ffi" =~ /\N{LATIN SMALL LIGATURE FFI}/ui + +are both true. Previously, there were many bugs with this feature. +What hasn't been fixed are the places where the pattern contains the +multiple characters, but the characters are split up by other things, +such as in + + "\N{LATIN SMALL LIGATURE FFI}" =~ /(f)(f)i/ui + +or + + "\N{LATIN SMALL LIGATURE FFI}" =~ /ffi*/ui + +or + + "\N{LATIN SMALL LIGATURE FFI}" =~ /[a-f][f-m][g-z]/ui + +None of these match. + +Also, this matching doesn't fully conform to the current Unicode +Standard, which asks that the matching be made upon the NFD +(Normalization Form Decomposed) of the text. However, as of this +writing (April 2010), the Unicode Standard is currently in flux about +what they will recommend doing with regard in such scenarios. It may be +that they will throw out the whole concept of multi-character matches. +[perl #71736]. + +=item * + +Naming a deprecated character in C<\N{I<NAME>}> no longer leaks memory. + +=item * + +We fixed a bug that could cause C<\N{I<NAME>}> constructs followed by +a single C<"."> to be parsed incorrectly [perl #74978] (5.12.1). + +=item * + +C<chop> now correctly handles characters above C<"\x{7fffffff}"> +[perl #73246]. + +=item * + +Passing to C<index> an offset beyond the end of the string when the string +is encoded internally in UTF8 no longer causes panics [perl #75898]. + +=item * + +warn() and die() now respect utf8-encoded scalars [perl #45549]. + +=item * + +Sometimes the UTF8 length cache would not be reset on a value +returned by substr, causing C<length(substr($uni_string, ...))> to give +wrong answers. With C<${^UTF8CACHE}> set to -1, it would also produce +a "panic" error message [perl #77692]. + +=back + +=head2 Ties, Overloading and Other Magic + +=over + +=item * + +Overloading now works properly in conjunction with tied +variables. What formerly happened was that most ops checked their +arguments for overloading I<before> checking for magic, so for example +an overloaded object returned by a tied array access would usually be +treated as not overloaded [RT #57012]. + +=item * + +Various instances of magic (like tie methods) being called on tied variables +too many or too few times have been fixed: + +=over + +=item * + +C<< $tied->() >> did not always call FETCH [perl #8438]. + +=item * + +Filetest operators and C<y///> and C<tr///> were calling FETCH too +many times. + +=item * + +The C<=> operator used to ignore magic on its right-hand side if the +scalar happened to hold a typeglob (if a typeglob was the last thing +returned from or assigned to a tied scalar) [perl #77498]. + +=item * + +Dereference operators used to ignore magic if the argument was a +reference already (such as from a previous FETCH) [perl #72144]. + +=item * + +C<splice> now calls set-magic (so changes made +by C<splice @ISA> are respected by method calls) [perl #78400]. + +=item * + +In-memory files created by C<< open($fh, ">", \$buffer) >> were not calling +FETCH/STORE at all [perl #43789] (5.12.2). + +=item * + +utf8::is_utf8() now respects get-magic (like C<$1>) (5.12.1). + +=back + +=item * + +Non-commutative binary operators used to swap their operands if the same +tied scalar was used for both operands and returned a different value for +each FETCH. For instance, if C<$t> returned 2 the first time and 3 the +second, then C<$t/$t> would evaluate to 1.5. This has been fixed +[perl #87708]. + +=item * + +String C<eval> now detects taintedness of overloaded or tied +arguments [perl #75716]. + +=item * + +String C<eval> and regular expression matches against objects with string +overloading no longer cause memory corruption or crashes [perl #77084]. + +=item * + +L<readline|perlfunc/"readline EXPR"> now honors C<< <> >> overloading on tied +arguments. + +=item * + +C<< <expr> >> always respects overloading now if the expression is +overloaded. + +Because "S<< <> as >> glob" was parsed differently from +"S<< <> as >> filehandle" from 5.6 onwards, something like C<< <$foo[0]> >> did +not handle overloading, even if C<$foo[0]> was an overloaded object. This +was contrary to the documentation for L<overload>, and meant that C<< <> >> +could not be used as a general overloaded iterator operator. + +=item * + +The fallback behaviour of overloading on binary operators was asymmetric +[perl #71286]. + +=item * + +Magic applied to variables in the main package no longer affects other packages. +See L</Magic variables outside the main package> above [perl #76138]. + +=item * + +Sometimes magic (ties, taintedness, etc.) attached to variables could cause +an object to last longer than it should, or cause a crash if a tied +variable were freed from within a tie method. These have been fixed +[perl #81230]. + +=item * + +DESTROY methods of objects implementing ties are no longer able to crash by +accessing the tied variable through a weak reference [perl #86328]. + +=item * + +Fixed a regression of kill() when a match variable is used for the +process ID to kill [perl #75812]. + +=item * + +C<$AUTOLOAD> used to remain tainted forever if it ever became tainted. Now +it is correctly untainted if an autoloaded method is called and the method +name was not tainted. + +=item * + +C<sprintf> now dies when passed a tainted scalar for the format. It did +already die for arbitrary expressions, but not for simple scalars +[perl #82250]. + +=item * + +C<lc>, C<uc>, C<lcfirst>, and C<ucfirst> no longer return untainted strings +when the argument is tainted. This has been broken since perl 5.8.9 +[perl #87336]. + +=back + +=head2 The Debugger + +=over + +=item * + +The Perl debugger now also works in taint mode [perl #76872]. + +=item * + +Subroutine redefinition works once more in the debugger [perl #48332]. + +=item * + +When B<-d> is used on the shebang (C<#!>) line, the debugger now has access +to the lines of the main program. In the past, this sometimes worked and +sometimes did not, depending on the order in which things happened to be +arranged in memory [perl #71806]. + +=item * + +A possible memory leak when using L<caller()|perlfunc/"caller EXPR"> to set +C<@DB::args> has been fixed (5.12.2). + +=item * + +Perl no longer stomps on C<$DB::single>, C<$DB::trace>, and C<$DB::signal> +if these variables already have values when C<$^P> is assigned to [perl #72422]. + +=item * + +C<#line> directives in string evals were not properly updating the arrays +of lines of code (C<< @{"_< ..."} >>) that the debugger (or any debugging or +profiling module) uses. In threaded builds, they were not being updated at +all. In non-threaded builds, the line number was ignored, so any change to +the existing line number would cause the lines to be misnumbered +[perl #79442]. + +=back + +=head2 Threads + +=over + +=item * + +Perl no longer accidentally clones lexicals in scope within active stack +frames in the parent when creating a child thread [perl #73086]. + +=item * + +Several memory leaks in cloning and freeing threaded Perl interpreters have been +fixed [perl #77352]. + +=item * + +Creating a new thread when directory handles were open used to cause a +crash, because the handles were not cloned, but simply passed to the new +thread, resulting in a double free. + +Now directory handles are cloned properly on Windows +and on systems that have a C<fchdir> function. On other +systems, new threads simply do not inherit directory +handles from their parent threads [perl #75154]. + +=item * + +The typeglob C<*,>, which holds the scalar variable C<$,> (output field +separator), had the wrong reference count in child threads. + +=item * + +[perl #78494] When pipes are shared between threads, the C<close> function +(and any implicit close, such as on thread exit) no longer blocks. + +=item * + +Perl now does a timely cleanup of SVs that are cloned into a new +thread but then discovered to be orphaned (that is, their owners +are I<not> cloned). This eliminates several "scalars leaked" +warnings when joining threads. + +=back + +=head2 Scoping and Subroutines + +=over + +=item * + +Lvalue subroutines are again able to return copy-on-write scalars. This +had been broken since version 5.10.0 [perl #75656] (5.12.3). + +=item * + +C<require> no longer causes C<caller> to return the wrong file name for +the scope that called C<require> and other scopes higher up that had the +same file name [perl #68712]. + +=item * + +C<sort> with a C<($$)>-prototyped comparison routine used to cause the value +of C<@_> to leak out of the sort. Taking a reference to C<@_> within the +sorting routine could cause a crash [perl #72334]. + +=item * + +Match variables (like C<$1>) no longer persist between calls to a sort +subroutine [perl #76026]. + +=item * + +Iterating with C<foreach> over an array returned by an lvalue sub now works +[perl #23790]. + +=item * + +C<$@> is now localised during calls to C<binmode> to prevent action at a +distance [perl #78844]. + +=item * + +Calling a closure prototype (what is passed to an attribute handler for a +closure) now results in a "Closure prototype called" error message instead +of a crash [perl #68560]. + +=item * + +Mentioning a read-only lexical variable from the enclosing scope in a +string C<eval> no longer causes the variable to become writable +[perl #19135]. + +=back + +=head2 Signals + +=over + +=item * + +Within signal handlers, C<$!> is now implicitly localized. + +=item * + +CHLD signals are no longer unblocked after a signal handler is called if +they were blocked before by C<POSIX::sigprocmask> [perl #82040]. + +=item * + +A signal handler called within a signal handler could cause leaks or +double-frees. Now fixed [perl #76248]. + +=back + +=head2 Miscellaneous Memory Leaks + +=over + +=item * + +Several memory leaks when loading XS modules were fixed (5.12.2). + +=item * + +L<substr()|perlfunc/"substr EXPR,OFFSET,LENGTH,REPLACEMENT">, +L<pos()|perlfunc/"index STR,SUBSTR,POSITION">, L<keys()|perlfunc/"keys HASH">, +and L<vec()|perlfunc/"vec EXPR,OFFSET,BITS"> could, when used in combination +with lvalues, result in leaking the scalar value they operate on, and cause its +destruction to happen too late. This has now been fixed. + +=item * + +The postincrement and postdecrement operators, C<++> and C<-->, used to cause +leaks when used on references. This has now been fixed. + +=item * + +Nested C<map> and C<grep> blocks no longer leak memory when processing +large lists [perl #48004]. + +=item * + +C<use I<VERSION>> and C<no I<VERSION>> no longer leak memory [perl #78436] +[perl #69050]. + +=item * + +C<.=> followed by C<< <> >> or C<readline> would leak memory if C<$/> +contained characters beyond the octet range and the scalar assigned to +happened to be encoded as UTF8 internally [perl #72246]. + +=item * + +C<eval 'BEGIN{die}'> no longer leaks memory on non-threaded builds. + +=back + +=head2 Memory Corruption and Crashes + +=over + +=item * + +glob() no longer crashes when C<%File::Glob::> is empty and +C<CORE::GLOBAL::glob> isn't present [perl #75464] (5.12.2). + +=item * + +readline() has been fixed when interrupted by signals so it no longer +returns the "same thing" as before or random memory. + +=item * + +When assigning a list with duplicated keys to a hash, the assignment used to +return garbage and/or freed values: + + @a = %h = (list with some duplicate keys); + +This has now been fixed [perl #31865]. + +=item * + +The mechanism for freeing objects in globs used to leave dangling +pointers to freed SVs, meaning Perl users could see corrupted state +during destruction. + +Perl now frees only the affected slots of the GV, rather than freeing +the GV itself. This makes sure that there are no dangling refs or +corrupted state during destruction. + +=item * + +The interpreter no longer crashes when freeing deeply-nested arrays of +arrays. Hashes have not been fixed yet [perl #44225]. + +=item * + +Concatenating long strings under C<use encoding> no longer causes Perl to +crash [perl #78674]. + +=item * + +Calling C<< ->import >> on a class lacking an import method could corrupt +the stack, resulting in strange behaviour. For instance, + + push @a, "foo", $b = bar->import; + +would assign "foo" to C<$b> [perl #63790]. + +=item * + +The C<recv> function could crash when called with the MSG_TRUNC flag +[perl #75082]. + +=item * + +C<formline> no longer crashes when passed a tainted format picture. It also +taints C<$^A> now if its arguments are tainted [perl #79138]. + +=item * + +A bug in how we process filetest operations could cause a segfault. +Filetests don't always expect an op on the stack, so we now use +TOPs only if we're sure that we're not C<stat>ing the C<_> filehandle. +This is indicated by C<OPf_KIDS> (as checked in ck_ftst) [perl #74542] +(5.12.1). + +=item * + +unpack() now handles scalar context correctly for C<%32H> and C<%32u>, +fixing a potential crash. split() would crash because the third item +on the stack wasn't the regular expression it expected. C<unpack("%2H", +...)> would return both the unpacked result and the checksum on the stack, +as would C<unpack("%2u", ...)> [perl #73814] (5.12.2). + +=back + +=head2 Fixes to Various Perl Operators + +=over + +=item * + +The C<&>, C<|>, and C<^> bitwise operators no longer coerce read-only arguments +[perl #20661]. + +=item * + +Stringifying a scalar containing "-0.0" no longer has the effect of turning +false into true [perl #45133]. + +=item * + +Some numeric operators were converting integers to floating point, +resulting in loss of precision on 64-bit platforms [perl #77456]. + +=item * + +sprintf() was ignoring locales when called with constant arguments +[perl #78632]. + +=item * + +Combining the vector (C<%v>) flag and dynamic precision would +cause C<sprintf> to confuse the order of its arguments, making it +treat the string as the precision and vice-versa [perl #83194]. + +=back + +=head2 Bugs Relating to the C API + +=over + +=item * + +The C-level C<lex_stuff_pvn> function would sometimes cause a spurious +syntax error on the last line of the file if it lacked a final semicolon +[perl #74006] (5.12.1). + +=item * + +The C<eval_sv> and C<eval_pv> C functions now set C<$@> correctly when +there is a syntax error and no C<G_KEEPERR> flag, and never set it if the +C<G_KEEPERR> flag is present [perl #3719]. + +=item * + +The XS multicall API no longer causes subroutines to lose reference counts +if called via the multicall interface from within those very subroutines. +This affects modules like L<List::Util>. Calling one of its functions with an +active subroutine as the first argument could cause a crash [perl #78070]. + +=item * + +The C<SvPVbyte> function available to XS modules now calls magic before +downgrading the SV, to avoid warnings about wide characters [perl #72398]. + +=item * + +The ref types in the typemap for XS bindings now support magical variables +[perl #72684]. + +=item * + +C<sv_catsv_flags> no longer calls C<mg_get> on its second argument (the +source string) if the flags passed to it do not include SV_GMAGIC. So it +now matches the documentation. + +=item * + +C<my_strftime> no longer leaks memory. This fixes a memory leak in +C<POSIX::strftime> [perl #73520]. + +=item * + +F<XSUB.h> now correctly redefines fgets under PERL_IMPLICIT_SYS [perl #55049] +(5.12.1). + +=item * + +XS code using fputc() or fputs() on Windows could cause an error +due to their arguments being swapped [perl #72704] (5.12.1). + +=item * + +A possible segfault in the C<T_PTROBJ> default typemap has been fixed +(5.12.2). + +=item * + +A bug that could cause "Unknown error" messages when +C<call_sv(code, G_EVAL)> is called from an XS destructor has been fixed +(5.12.2). + +=back + +=head1 Known Problems + +This is a list of significant unresolved issues which are regressions +from earlier versions of Perl or which affect widely-used CPAN modules. + +=over 4 + +=item * + +C<List::Util::first> misbehaves in the presence of a lexical C<$_> +(typically introduced by C<my $_> or implicitly by C<given>). The variable +that gets set for each iteration is the package variable C<$_>, not the +lexical C<$_>. + +A similar issue may occur in other modules that provide functions which +take a block as their first argument, like + + foo { ... $_ ...} list + +See also: L<http://rt.perl.org/rt3/Public/Bug/Display.html?id=67694> + +=item * + +readline() returns an empty string instead of undef when it is +interrupted by a signal. + +=item * + +The changes in prototype handling break L<Switch>. A patch has been sent +upstream and will hopefully appear on CPAN soon. + +=item * + +The upgrade to F<ExtUtils-MakeMaker-6.57_05> has caused +some tests in the F<Module-Install> distribution on CPAN to +fail. (Specifically, F<02_mymeta.t> tests 5 and 21; F<18_all_from.t> +tests 6 and 15; F<19_authors.t> tests 5, 13, 21, and 29; and +F<20_authors_with_special_characters.t> tests 6, 15, and 23 in version +1.00 of that distribution now fail.) + +=item * + +On VMS, C<Time::HiRes> tests will fail due to a bug in the CRTL's +implementation of C<setitimer>: previous timer values would be cleared +if a timer expired but not if the timer was reset before expiring. HP +OpenVMS Engineering have corrected the problem and will release a patch +in due course (Quix case # QXCM1001115136). + +=item * + +On VMS, there were a handful of C<Module::Build> test failures we didn't +get to before the release; please watch CPAN for updates. + +=back + +=head1 Errata + +=head2 keys(), values(), and each() work on arrays + +You can now use the keys(), values(), and each() builtins on arrays; +previously you could use them only on hashes. See L<perlfunc> for details. +This is actually a change introduced in perl 5.12.0, but it was missed from +that release's L<perl5120delta>. + +=head2 split() and C<@_> + +split() no longer modifies C<@_> when called in scalar or void context. +In void context it now produces a "Useless use of split" warning. +This was also a perl 5.12.0 change that missed the perldelta. + +=head1 Obituary + +Randy Kobes, creator of http://kobesearch.cpan.org/ and +contributor/maintainer to several core Perl toolchain modules, passed +away on September 18, 2010 after a battle with lung cancer. The community +was richer for his involvement. He will be missed. + +=head1 Acknowledgements + +Perl 5.14.0 represents one year of development since +Perl 5.12.0 and contains nearly 550,000 lines of changes across nearly +3,000 files from 150 authors and committers. + +Perl continues to flourish into its third decade thanks to a vibrant +community of users and developers. The following people are known to +have contributed the improvements that became Perl 5.14.0: + +Aaron Crane, Abhijit Menon-Sen, Abigail, Ævar Arnfjörð Bjarmason, +Alastair Douglas, Alexander Alekseev, Alexander Hartmaier, Alexandr +Ciornii, Alex Davies, Alex Vandiver, Ali Polatel, Allen Smith, Andreas +König, Andrew Rodland, Andy Armstrong, Andy Dougherty, Aristotle +Pagaltzis, Arkturuz, Arvan, A. Sinan Unur, Ben Morrow, Bo Lindbergh, +Boris Ratner, Brad Gilbert, Bram, brian d foy, Brian Phillips, Casey +West, Charles Bailey, Chas. Owens, Chip Salzenberg, Chris 'BinGOs' +Williams, chromatic, Craig A. Berry, Curtis Jewell, Dagfinn Ilmari +MannsÃ¥ker, Dan Dascalescu, Dave Rolsky, David Caldwell, David Cantrell, +David Golden, David Leadbeater, David Mitchell, David Wheeler, Eric +Brine, Father Chrysostomos, Fingle Nark, Florian Ragwitz, Frank Wiegand, +Franz Fasching, Gene Sullivan, George Greer, Gerard Goossen, Gisle Aas, +Goro Fuji, Grant McLean, gregor herrmann, H.Merijn Brand, Hongwen Qiu, +Hugo van der Sanden, Ian Goodacre, James E Keenan, James Mastros, Jan +Dubois, Jay Hannah, Jerry D. Hedden, Jesse Vincent, Jim Cromie, Jirka +HruÅ¡ka, John Peacock, Joshua ben Jore, Joshua Pritikin, Karl Williamson, +Kevin Ryde, kmx, Lars Dɪᴇᴄᴋá´á´¡ 迪拉斯, Larwan Berke, Leon Brocard, Leon +Timmermans, Lubomir Rintel, Lukas Mai, Maik Hentsche, Marty Pauley, +Marvin Humphrey, Matt Johnson, Matt S Trout, Max Maischein, Michael +Breen, Michael Fig, Michael G Schwern, Michael Parker, Michael Stevens, +Michael Witten, Mike Kelly, Moritz Lenz, Nicholas Clark, Nick Cleaton, +Nick Johnston, Nicolas Kaiser, Niko Tyni, Noirin Shirley, Nuno Carvalho, +Paul Evans, Paul Green, Paul Johnson, Paul Marquess, Peter J. Holzer, +Peter John Acklam, Peter Martini, Philippe Bruhat (BooK), Piotr Fusik, +Rafael Garcia-Suarez, Rainer Tammer, Reini Urban, Renee Baecker, Ricardo +Signes, Richard Möhn, Richard Soderberg, Rob Hoelz, Robin Barker, Ruslan +Zakirov, Salvador Fandiño, Salvador Ortiz Garcia, Shlomi Fish, Sinan +Unur, Sisyphus, Slaven Rezic, Steffen Müller, Steve Hay, Steven +Schubiger, Steve Peters, Sullivan Beck, Tatsuhiko Miyagawa, Tim Bunce, +Todd Rinaldo, Tom Christiansen, Tom Hukins, Tony Cook, Tye McQueen, +Vadim Konovalov, Vernon Lyon, Vincent Pit, Walt Mankowski, Wolfram +Humann, Yves Orton, Zefram, and Zsbán Ambrus. + +This is woefully incomplete as it's automatically generated from version +control history. In particular, it doesn't include the names of the +(very much appreciated) contributors who reported issues in previous +versions of Perl that helped make Perl 5.14.0 better. For a more complete +list of all of Perl's historical contributors, please see the C<AUTHORS> +file in the Perl 5.14.0 distribution. + +Many of the changes included in this version originated in the CPAN +modules included in Perl's core. We're grateful to the entire CPAN +community for helping Perl to flourish. + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the Perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the L<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please use this address for +security issues in the Perl core I<only>, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5141delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5141delta.pod new file mode 100644 index 00000000000..db24343c695 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5141delta.pod @@ -0,0 +1,361 @@ +=encoding utf8 + +=head1 NAME + +perl5141delta - what is new for perl v5.14.1 + +=head1 DESCRIPTION + +This document describes differences between the 5.14.0 release and +the 5.14.1 release. + +If you are upgrading from an earlier release such as 5.12.0, first read +L<perl5140delta>, which describes differences between 5.12.0 and +5.14.0. + +=head1 Core Enhancements + +No changes since 5.14.0. + +=head1 Security + +No changes since 5.14.0. + +=head1 Incompatible Changes + +There are no changes intentionally incompatible with 5.14.0. If any +exist, they are bugs and reports are welcome. + +=head1 Deprecations + +There have been no deprecations since 5.14.0. + +=head1 Modules and Pragmata + +=head2 New Modules and Pragmata + +None + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +L<B::Deparse> has been upgraded from version 1.03 to 1.04, to address two +regressions in Perl 5.14.0: + +Deparsing of the C<glob> operator and its diamond (C<< <> >>) form now +works again. [perl #90898] + +The presence of subroutines named C<::::> or C<::::::> no longer causes +B::Deparse to hang. + +=item * + +L<Pod::Perldoc> has been upgraded from version 3.15_03 to 3.15_04. + +It corrects the search paths on VMS. [perl #90640] + +=back + +=head2 Removed Modules and Pragmata + +None + +=head1 Documentation + +=head2 New Documentation + +None + +=head2 Changes to Existing Documentation + +=head3 L<perlfunc> + +=over + +=item * + +C<given>, C<when> and C<default> are now listed in L<perlfunc>. + +=item * + +Documentation for C<use> now includes a pointer to F<if.pm>. + +=back + +=head3 L<perllol> + +=over + +=item * + +L<perllol> has been expanded with examples using the new C<push $scalar> +syntax introduced in Perl 5.14.0. + +=back + +=head3 L<perlop> + +=over 4 + +=item * + +The explanation of bitwise operators has been expanded to explain how they +work on Unicode strings. + +=item * + +The section on the triple-dot or yada-yada operator has been moved up, as +it used to separate two closely related sections about the comma operator. + +=item * + +More examples for C<m//g> have been added. + +=item * + +The C<<< <<\FOO >>> here-doc syntax has been documented. + +=back + +=head3 L<perlrun> + +=over + +=item * + +L<perlrun> has undergone a significant clean-up. Most notably, the +B<-0x...> form of the B<-0> flag has been clarified, and the final section +on environment variables has been corrected and expanded. + +=back + +=head3 L<POSIX> + +=over + +=item * + +The invocation documentation for C<WIFEXITED>, C<WEXITSTATUS>, +C<WIFSIGNALED>, C<WTERMSIG>, C<WIFSTOPPED>, and C<WSTOPSIG> was corrected. + +=back + + +=head1 Diagnostics + +The following additions or changes have been made to diagnostic output, +including warnings and fatal error messages. For the complete list of +diagnostic messages, see L<perldiag>. + +=head2 New Diagnostics + +None + +=head2 Changes to Existing Diagnostics + +None + +=head1 Utility Changes + +None + +=head1 Configuration and Compilation + +=over 4 + +=item * + +F<regexp.h> has been modified for compatibility with GCC's C<-Werror> +option, as used by some projects that include perl's header files. + +=back + +=head1 Testing + +=over 4 + +=item * + +Some test failures in F<dist/Locale-Maketext/t/09_compile.t> that could +occur depending on the environment have been fixed. [perl #89896] + +=item * + +A watchdog timer for F<t/re/re.t> was lengthened to accommodate SH-4 systems +which were unable to complete the tests before the previous timer ran out. + + +=back + +=head1 Platform Support + +=head2 New Platforms + +None + +=head2 Discontinued Platforms + +None + +=head2 Platform-Specific Notes + +=head3 Solaris + +=over + +=item * + +Documentation listing the Solaris packages required to build Perl on +Solaris 9 and Solaris 10 has been corrected. + +=back + +=head3 Mac OS X + +=over + +=item * + +The F<lib/locale.t> test script has been updated to work on the upcoming +Lion release. + +=item * + +Mac OS X specific compilation instructions have been clarified. + +=back + +=head3 Ubuntu Linux + +=over + +=item * + +The L<ODBM_File> installation process has been updated with the new library +paths on Ubuntu natty. + +=back + +=head1 Internal Changes + +=over + +=item * + +The compiled representation of formats is now stored via the mg_ptr of +their PERL_MAGIC_fm. Previously it was stored in the string buffer, +beyond SvLEN(), the regular end of the string. SvCOMPILED() and +SvCOMPILED_{on,off}() now exist solely for compatibility for XS code. +The first is always 0, the other two now no-ops. + +=back + +=head1 Bug Fixes + +=over 4 + +=item * + +A bug has been fixed that would cause a "Use of freed value in iteration" +error if the next two hash elements that would be iterated over are +deleted. [perl #85026] + +=item * + +Passing the same constant subroutine to both C<index> and C<formline> no +longer causes one or the other to fail. [perl #89218] + +=item * + +5.14.0 introduced some memory leaks in regular expression character +classes such as C<[\w\s]>, which have now been fixed. + +=item * + +An edge case in regular expression matching could potentially loop. +This happened only under C</i> in bracketed character classes that have +characters with multi-character folds, and the target string to match +against includes the first portion of the fold, followed by another +character that has a multi-character fold that begins with the remaining +portion of the fold, plus some more. + + "s\N{U+DF}" =~ /[\x{DF}foo]/i + +is one such case. C<\xDF> folds to C<"ss">. + +=item * + +Several Unicode case-folding bugs have been fixed. + +=item * + +The new (in 5.14.0) regular expression modifier C</a> when repeated like +C</aa> forbids the characters outside the ASCII range that match +characters inside that range from matching under C</i>. This did not +work under some circumstances, all involving alternation, such as: + + "\N{KELVIN SIGN}" =~ /k|foo/iaa; + +succeeded inappropriately. This is now fixed. + +=item * + +Fixed a case where it was possible that a freed buffer may have been read +from when parsing a here document. + +=back + +=head1 Acknowledgements + +Perl 5.14.1 represents approximately four weeks of development since +Perl 5.14.0 and contains approximately 3500 lines of changes +across 38 files from 17 authors. + +Perl continues to flourish into its third decade thanks to a vibrant +community of users and developers. The following people are known to +have contributed the improvements that became Perl 5.14.1: + +Bo Lindbergh, Claudio Ramirez, Craig A. Berry, David Leadbeater, Father +Chrysostomos, Jesse Vincent, Jim Cromie, Justin Case, Karl Williamson, +Leo Lapworth, Nicholas Clark, Nobuhiro Iwamatsu, smash, Tom Christiansen, +Ton Hospel, Vladimir Timofeev, and Zsbán Ambrus. + + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the L<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl5142delta.pod b/Master/tlpkg/tlperl/lib/pods/perl5142delta.pod new file mode 100644 index 00000000000..425708fbb46 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perl5142delta.pod @@ -0,0 +1,242 @@ +=encoding utf8 + +=head1 NAME + +perldelta - what is new for perl v5.14.2 + +=head1 DESCRIPTION + +This document describes differences between the 5.14.1 release and +the 5.14.2 release. + +If you are upgrading from an earlier release such as 5.14.0, first read +L<perl5141delta>, which describes differences between 5.14.0 and +5.14.1. + +=head1 Core Enhancements + +No changes since 5.14.0. + +=head1 Security + +=head2 C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC (CVE-2011-2728). + +Calling C<File::Glob::bsd_glob> with the unsupported flag GLOB_ALTDIRFUNC would +cause an access violation / segfault. A Perl program that accepts a flags value from +an external source could expose itself to denial of service or arbitrary code +execution attacks. There are no known exploits in the wild. The problem has been +corrected by explicitly disabling all unsupported flags and setting unused function +pointers to null. Bug reported by Clément Lecigne. + +=head2 C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939) + +A bug in C<Encode> could, on certain inputs, cause the heap to overflow. +This problem has been corrected. Bug reported by Robert Zacek. + +=head1 Incompatible Changes + +There are no changes intentionally incompatible with 5.14.0. If any +exist, they are bugs and reports are welcome. + +=head1 Deprecations + +There have been no deprecations since 5.14.0. + +=head1 Modules and Pragmata + +=head2 New Modules and Pragmata + +None + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +L<CPAN> has been upgraded from version 1.9600 to version 1.9600_01. + +L<CPAN::Distribution> has been upgraded from version 1.9602 to 1.9602_01. + +Backported bugfixes from CPAN version 1.9800. Ensures proper +detection of C<configure_requires> prerequisites from CPAN Meta files +in the case where C<dynamic_config> is true. [rt.cpan.org #68835] + +Also ensures that C<configure_requires> is only checked in META files, +not MYMETA files, so protect against MYMETA generation that drops +C<configure_requires>. + +=item * + +L<Encode> has been upgraded from version 2.42 to 2.42_01. + +See L</Security>. + +=item * + +L<File::Glob> has been upgraded from version 1.12 to version 1.13. + +See L</Security>. + +=item * + +L<PerlIO::scalar> has been upgraded from version 0.11 to 0.11_01. + +It fixes a problem with C<< open my $fh, ">", \$scalar >> not working if +C<$scalar> is a copy-on-write scalar. + +=back + +=head2 Removed Modules and Pragmata + +None + +=head1 Platform Support + +=head2 New Platforms + +None + +=head2 Discontinued Platforms + +None + +=head2 Platform-Specific Notes + +=over 4 + +=item HP-UX PA-RISC/64 now supports gcc-4.x + +A fix to correct the socketsize now makes the test suite pass on HP-UX +PA-RISC for 64bitall builds. + +=item Building on OS X 10.7 Lion and Xcode 4 works again + +The build system has been updated to work with the build tools under Mac OS X +10.7. + +=back + +=head1 Bug Fixes + +=over 4 + +=item * + +In @INC filters (subroutines returned by subroutines in @INC), $_ used to +misbehave: If returned from a subroutine, it would not be copied, but the +variable itself would be returned; and freeing $_ (e.g., with C<undef *_>) +would cause perl to crash. This has been fixed [perl #91880]. + +=item * + +Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of +a pack template equivalent to "U0" if the input string was empty. This has +been fixed [perl #90160]. + +=item * + +C<caller> no longer leaks memory when called from the DB package if +C<@DB::args> was assigned to after the first call to C<caller>. L<Carp> +was triggering this bug [perl #97010]. + +=item * + +C<utf8::decode> had a nasty bug that would modify copy-on-write scalars' +string buffers in place (i.e., skipping the copy). This could result in +hashes having two elements with the same key [perl #91834]. + +=item * + +Localising a tied variable used to make it read-only if it contained a +copy-on-write string. + +=item * + +Elements of restricted hashes (see the L<fields> pragma) containing +copy-on-write values couldn't be deleted, nor could such hashes be cleared +(C<%hash = ()>). + +=item * + +Locking a hash element that is a glob copy no longer causes subsequent +assignment to it to corrupt the glob. + +=item * + +A panic involving the combination of the regular expression modifiers +C</aa> introduced in 5.14.0 and the C<\b> escape sequence has been +fixed [perl #95964]. + +=back + +=head1 Known Problems + +This is a list of some significant unfixed bugs, which are regressions +from 5.12.0. + +=over 4 + +=item * + +C<PERL_GLOBAL_STRUCT> is broken. + +Since perl 5.14.0, building with C<-DPERL_GLOBAL_STRUCT> hasn't been +possible. This means that perl currently doesn't work on any platforms that +require it to be built this way, including Symbian. + +While C<PERL_GLOBAL_STRUCT> now works again on recent development versions of +perl, it actually working on Symbian again hasn't been verified. + +We'd be very interested in hearing from anyone working with Perl on Symbian. + +=back + +=head1 Acknowledgements + +Perl 5.14.2 represents approximately three months of development since +Perl 5.14.1 and contains approximately 1200 lines of changes +across 61 files from 9 authors. + +Perl continues to flourish into its third decade thanks to a vibrant +community of users and developers. The following people are known to +have contributed the improvements that became Perl 5.14.2: + +Craig A. Berry, David Golden, Father Chrysostomos, Florian Ragwitz, H.Merijn +Brand, Karl Williamson, Nicholas Clark, Pau Amma and Ricardo Signes. + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the articles +recently posted to the comp.lang.perl.misc newsgroup and the perl +bug database at http://rt.perl.org/perlbug/ . There may also be +information at http://www.perl.org/ , the Perl Home Page. + +If you believe you have an unreported bug, please run the L<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.org to be +analysed by the Perl porting team. + +If the bug you are reporting has security implications, which make it +inappropriate to send to a publicly archived mailing list, then please send +it to perl5-security-report@perl.org. This points to a closed subscription +unarchived mailing list, which includes all the core committers, who be able +to help assess the impact of issues, figure out a resolution, and help +co-ordinate the release of patches to mitigate or fix the problem across all +platforms on which Perl is supported. Please only use this address for +security issues in the Perl core, not for modules independently +distributed on CPAN. + +=head1 SEE ALSO + +The F<Changes> file for an explanation of how to view exhaustive details +on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perl572delta.pod b/Master/tlpkg/tlperl/lib/pods/perl572delta.pod index 21585edc4e0..67d091262e9 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl572delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl572delta.pod @@ -760,10 +760,10 @@ hard-to-fix ways. As a stop-gap measure to avoid people from getting frustrated at the mysterious results (core dumps, most often) it is for now forbidden (you will get a fatal error even from an attempt). -=head2 Variable Attributes are not Currently Usable for Tieing +=head2 Variable Attributes are not Currently Usable for Tying This limitation will hopefully be fixed in future. (Subroutine -attributes work fine for tieing, see L<Attribute::Handlers>). +attributes work fine for tying, see L<Attribute::Handlers>). =head2 Building Extensions Can Fail Because Of Largefiles diff --git a/Master/tlpkg/tlperl/lib/pods/perl588delta.pod b/Master/tlpkg/tlperl/lib/pods/perl588delta.pod index a3d1df35b38..b2203bcf71d 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl588delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl588delta.pod @@ -1,3 +1,5 @@ +=encoding utf8 + =head1 NAME perl588delta - what is new for perl v5.8.8 diff --git a/Master/tlpkg/tlperl/lib/pods/perl589delta.pod b/Master/tlpkg/tlperl/lib/pods/perl589delta.pod index 2070cc3aa44..8cd1cf67348 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl589delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl589delta.pod @@ -92,7 +92,7 @@ C<system> operator. See L<perlvar> for details. (Contributed by Gisle Aas.) This variable controls the state of the internal UTF-8 offset caching code. 1 for on (the default), 0 for off, -1 to debug the caching code by checking -all its results against linear scans, and panicing on any discrepancy. +all its results against linear scans, and panicking on any discrepancy. =back @@ -1655,7 +1655,7 @@ a C<system> call. =item * -Fixed bug RT #37886, symbolic deferencing was allowed in the argument of +Fixed bug RT #37886, symbolic dereferencing was allowed in the argument of C<defined> even under the influence of C<use strict 'refs'>. =item * @@ -1811,7 +1811,7 @@ The process id is no longer truncated to 16 bits on some Windows platforms =item * -Fixed bug RT #54828 in F<perlio.c> where calling C<binmode> on Win32 and Cgywin +Fixed bug RT #54828 in F<perlio.c> where calling C<binmode> on Win32 and Cygwin may cause a segmentation fault. =back diff --git a/Master/tlpkg/tlperl/lib/pods/perl592delta.pod b/Master/tlpkg/tlperl/lib/pods/perl592delta.pod index 9648843d79e..db8be417d2b 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl592delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl592delta.pod @@ -242,7 +242,7 @@ C<map> in scalar context is now optimized. =item * The regexp engine now implements the trie optimization : it's able to -factorize common prefixes and suffixes in regular expressions. A new +factor out common prefixes and suffixes in regular expressions. A new special variable, ${^RE_TRIE_MAXBUF}, has been added to fine-tune this optimization. diff --git a/Master/tlpkg/tlperl/lib/pods/perl593delta.pod b/Master/tlpkg/tlperl/lib/pods/perl593delta.pod index 6c8587aee9e..11f53ab0885 100644 --- a/Master/tlpkg/tlperl/lib/pods/perl593delta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perl593delta.pod @@ -1,3 +1,5 @@ +=encoding utf8 + =head1 NAME perl593delta - what is new for perl v5.9.3 diff --git a/Master/tlpkg/tlperl/lib/pods/perlaix.pod b/Master/tlpkg/tlperl/lib/pods/perlaix.pod index 6b86ba62154..6437f51d5fa 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlaix.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlaix.pod @@ -77,18 +77,18 @@ at least gdbm-devel-1.8.3-5 (or higher). Perl | AIX Level | Compiler Level | w th | w/o th -------+---------------------+-------------------------+------+------- - 5.12.3 |5.1 TL9 32 bit | XL C/C++ V7 | OK | OK - 5.12.3 |5.1 TL9 64 bit | XL C/C++ V7 | OK | OK - 5.12.3 |5.2 TL10 SP8 32 bit | XL C/C++ V8 | OK | OK - 5.12.3 |5.2 TL10 SP8 32 bit | gcc 3.2.2 | OK | OK - 5.12.3 |5.2 TL10 SP8 64 bit | XL C/C++ V8 | OK | OK - 5.12.3 |5.3 TL8 SP8 32 bit | XL C/C++ V9 + IZ35785 | OK | OK - 5.12.3 |5.3 TL8 SP8 32 bit | gcc 4.2.4 | OK | OK - 5.12.3 |5.3 TL8 SP8 64 bit | XL C/C++ V9 + IZ35785 | OK | OK - 5.12.3 |5.3 TL10 SP3 32 bit | XL C/C++ V11 + Apr 2010 | OK | OK - 5.12.3 |5.3 TL10 SP3 64 bit | XL C/C++ V11 + Apr 2010 | OK | OK - 5.12.3 |6.1 TL1 SP7 32 bit | XL C/C++ V10 | OK | OK - 5.12.3 |6.1 TL1 SP7 64 bit | XL C/C++ V10 | OK | OK + 5.12.2 |5.1 TL9 32 bit | XL C/C++ V7 | OK | OK + 5.12.2 |5.1 TL9 64 bit | XL C/C++ V7 | OK | OK + 5.12.2 |5.2 TL10 SP8 32 bit | XL C/C++ V8 | OK | OK + 5.12.2 |5.2 TL10 SP8 32 bit | gcc 3.2.2 | OK | OK + 5.12.2 |5.2 TL10 SP8 64 bit | XL C/C++ V8 | OK | OK + 5.12.2 |5.3 TL8 SP8 32 bit | XL C/C++ V9 + IZ35785 | OK | OK + 5.12.2 |5.3 TL8 SP8 32 bit | gcc 4.2.4 | OK | OK + 5.12.2 |5.3 TL8 SP8 64 bit | XL C/C++ V9 + IZ35785 | OK | OK + 5.12.2 |5.3 TL10 SP3 32 bit | XL C/C++ V11 + Apr 2010 | OK | OK + 5.12.2 |5.3 TL10 SP3 64 bit | XL C/C++ V11 + Apr 2010 | OK | OK + 5.12.2 |6.1 TL1 SP7 32 bit | XL C/C++ V10 | OK | OK + 5.12.2 |6.1 TL1 SP7 64 bit | XL C/C++ V10 | OK | OK 5.13 |7.1 TL0 SP1 32 bit | XL C/C++ V11 + Jul 2010 | OK | OK 5.13 |7.1 TL0 SP1 64 bit | XL C/C++ V11 + Jul 2010 | OK | OK @@ -484,11 +484,6 @@ therefore in AIX 4.2 Perl is not linked against the libC_r. =head1 AUTHORS -H.Merijn Brand <h.m.brand@xs4all.nl> Rainer Tammer <tammer@tammer.net> -=head1 DATE - -Version 5.12.1 / 2010-05-14 - =cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlamiga.pod b/Master/tlpkg/tlperl/lib/pods/perlamiga.pod index 418a5fe635f..c86adefe7b4 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlamiga.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlamiga.pod @@ -67,7 +67,7 @@ Contents You need the Unix emulation for AmigaOS, whose most important part is B<ixemul.library>. For a minimum setup, get the latest versions of the following packages from the Aminet archives -( http://www.aminet.net/~aminet/ ): +( L<http://www.aminet.net/~aminet/> ): ixemul-bin ixemul-env-bin diff --git a/Master/tlpkg/tlperl/lib/pods/perlapi.pod b/Master/tlpkg/tlperl/lib/pods/perlapi.pod index 3a8792b899d..5c7a2b98bfd 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlapi.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlapi.pod @@ -13,10 +13,12 @@ X<Perl API> X<API> X<api> This file contains the documentation of the perl public API generated by embed.pl, specifically a listing of functions, macros, flags, and variables -that may be used by extension writers. The interfaces of any functions that -are not listed here are subject to change without notice. For this reason, -blindly using functions listed in proto.h is to be avoided when writing -extensions. +that may be used by extension writers. L<At the end|/Undocumented functions> +is a list of functions which have yet to be documented. The interfaces of +those are subject to change without notice. Any functions not listed here are +not part of the public API, and should not be used by extension writers at +all. For these reasons, blindly using functions listed in proto.h is to be +avoided when writing extensions. Note that all Perl API global variables must be referenced with the C<PL_> prefix. Some macros are provided for compatibility with the older, @@ -69,7 +71,7 @@ X<GIMME_V> The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context, -respectively. +respectively. See L<perlcall> for a usage example. U32 GIMME_V @@ -150,7 +152,7 @@ Found in file av.h X<av_clear> Clears an array, making it empty. Does not free the memory used by the -array itself. +array itself. Perl equivalent: C<@myarray = ();>. void av_clear(AV *av) @@ -189,9 +191,11 @@ Found in file av.c =item av_delete X<av_delete> -Deletes the element indexed by C<key> from the array. Returns the -deleted element. If C<flags> equals C<G_DISCARD>, the element is freed -and null is returned. +Deletes the element indexed by C<key> from the array, makes the element mortal, +and returns it. If C<flags> equals C<G_DISCARD>, the element is freed and null +is returned. Perl equivalent: C<my $elem = delete($myarray[$idx]);> for the +non-C<G_DISCARD> version and a void-context C<delete($myarray[$idx]);> for the +C<G_DISCARD> version. SV* av_delete(AV *av, I32 key, I32 flags) @@ -206,6 +210,8 @@ Returns true if the element indexed by C<key> has been initialized. This relies on the fact that uninitialized array elements are set to C<&PL_sv_undef>. +Perl equivalent: C<exists($myarray[$key])>. + bool av_exists(AV *av, I32 key) =for hackers @@ -226,12 +232,14 @@ Found in file av.c X<av_fetch> Returns the SV at the specified index in the array. The C<key> is the -index. If C<lval> is set then the fetch will be part of a store. Check -that the return value is non-null before dereferencing it to a C<SV*>. +index. If lval is true, you are guaranteed to get a real SV back (in case +it wasn't real before), which you can then modify. Check that the return +value is non-null before dereferencing it to a C<SV*>. See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more information on how to use this function on tied arrays. +The rough perl equivalent is C<$myarray[$idx]>. SV** av_fetch(AV *av, I32 key, I32 lval) =for hackers @@ -244,7 +252,7 @@ Set the highest index in the array to the given number, equivalent to Perl's C<$#array = $fill;>. The number of elements in the an array will be C<fill + 1> after -av_fill() returns. If the array was previously shorter then the +av_fill() returns. If the array was previously shorter, then the additional elements appended are set to C<PL_sv_undef>. If the array was longer, then the excess elements are freed. C<av_fill(av, -1)> is the same as C<av_clear(av)>. @@ -260,6 +268,8 @@ 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. +The Perl equivalent for this is C<$#myarray>. + I32 av_len(AV *av) =for hackers @@ -272,6 +282,8 @@ Creates a new AV and populates it with a list of SVs. The SVs are copied into the array, so they may be freed after the call to av_make. The new AV will have a reference count of 1. +Perl equivalent: C<my @new_array = ($scalar1, $scalar2, $scalar3...);> + AV* av_make(I32 size, SV **strp) =for hackers @@ -292,8 +304,7 @@ Found in file av.c X<av_push> Pushes an SV onto the end of the array. The array will grow automatically -to accommodate the addition. Like C<av_store>, this takes ownership of one -reference count. +to accommodate the addition. This takes ownership of one reference count. void av_push(AV *av, SV *val) @@ -484,7 +495,8 @@ Found in file perl.c =item eval_sv X<eval_sv> -Tells Perl to C<eval> the string in the SV. +Tells Perl to C<eval> the string in the SV. It supports the same flags +as C<call_sv>, with the obvious exception of G_EVAL. See L<perlcall>. NOTE: the perl_ form of this function is deprecated. @@ -528,37 +540,92 @@ Found in file scope.h =back -=head1 Character classes +=head1 Character case changing =over 8 -=item isALNUM -X<isALNUM> +=item toLOWER +X<toLOWER> -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -alphanumeric character (including underscore) or digit. +Converts the specified character to lowercase in the platform's native +character set, if possible; otherwise returns the input character itself. - bool isALNUM(char ch) + char toLOWER(char ch) =for hackers Found in file handy.h +=item toUPPER +X<toUPPER> + +Converts the specified character to uppercase in the platform's native +character set, if possible; otherwise returns the input character itself. + + char toUPPER(char ch) + +=for hackers +Found in file handy.h + + +=back + +=head1 Character classes + +There are three variants for all the functions in this section. The base ones +operate using the character set of the platform Perl is running on. The ones +with an C<_A> suffix operate on the ASCII character set, and the ones with an +C<_L1> suffix operate on the full Latin1 character set. All are unaffected by +locale + +For ASCII platforms, the base function with no suffix and the one with the +C<_A> suffix are identical. The function with the C<_L1> suffix imposes the +Latin-1 character set onto the platform. That is, the code points that are +ASCII are unaffected, since ASCII is a subset of Latin-1. But the non-ASCII +code points are treated as if they are Latin-1 characters. For example, +C<isSPACE_L1()> will return true when called with the code point 0xA0, which is +the Latin-1 NO-BREAK SPACE. + +For EBCDIC platforms, the base function with no suffix and the one with the +C<_L1> suffix should be identical, since, as of this writing, the EBCDIC code +pages that Perl knows about all are equivalent to Latin-1. The function that +ends in an C<_A> suffix will not return true unless the specified character also +has an ASCII equivalent. + + +=over 8 + =item isALPHA X<isALPHA> -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -alphabetic character. +Returns a boolean indicating whether the specified character is an +alphabetic character in the platform's native character set. +See the L<top of this section|/Character classes> for an explanation of variants +C<isALPHA_A> and C<isALPHA_L1>. bool isALPHA(char ch) =for hackers Found in file handy.h +=item isASCII +X<isASCII> + +Returns a boolean indicating whether the specified character is one of the 128 +characters in the ASCII character set. On non-ASCII platforms, it is if this +character corresponds to an ASCII character. Variants C<isASCII_A()> and +C<isASCII_L1()> are identical to C<isASCII()>. + + bool isASCII(char ch) + +=for hackers +Found in file handy.h + =item isDIGIT X<isDIGIT> -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -digit. +Returns a boolean indicating whether the specified character is a +digit in the platform's native character set. +Variants C<isDIGIT_A> and C<isDIGIT_L1> are identical to C<isDIGIT>. bool isDIGIT(char ch) @@ -568,19 +635,36 @@ Found in file handy.h =item isLOWER X<isLOWER> -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -lowercase character. +Returns a boolean indicating whether the specified character is a +lowercase character in the platform's native character set. +See the L<top of this section|/Character classes> for an explanation of variants +C<isLOWER_A> and C<isLOWER_L1>. bool isLOWER(char ch) =for hackers Found in file handy.h +=item isOCTAL +X<isOCTAL> + +Returns a boolean indicating whether the specified character is an +octal digit, [0-7] in the platform's native character set. +Variants C<isOCTAL_A> and C<isOCTAL_L1> are identical to C<isOCTAL>. + + bool isOCTAL(char ch) + +=for hackers +Found in file handy.h + =item isSPACE X<isSPACE> -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -whitespace. +Returns a boolean indicating whether the specified character is a +whitespace character in the platform's native character set. This is the same +as what C<\s> matches in a regular expression. +See the L<top of this section|/Character classes> for an explanation of variants +C<isSPACE_A> and C<isSPACE_L1>. bool isSPACE(char ch) @@ -590,32 +674,41 @@ Found in file handy.h =item isUPPER X<isUPPER> -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -uppercase character. +Returns a boolean indicating whether the specified character is an +uppercase character in the platform's native character set. +See the L<top of this section|/Character classes> for an explanation of variants +C<isUPPER_A> and C<isUPPER_L1>. bool isUPPER(char ch) =for hackers Found in file handy.h -=item toLOWER -X<toLOWER> +=item isWORDCHAR +X<isWORDCHAR> -Converts the specified character to lowercase. Characters outside the -US-ASCII (Basic Latin) range are viewed as not having any case. +Returns a boolean indicating whether the specified character is a +character that is any of: alphabetic, numeric, or an underscore. This is the +same as what C<\w> matches in a regular expression. +C<isALNUM()> is a synonym provided for backward compatibility. Note that it +does not have the standard C language meaning of alphanumeric, since it matches +an underscore and the standard meaning does not. +See the L<top of this section|/Character classes> for an explanation of variants +C<isWORDCHAR_A> and C<isWORDCHAR_L1>. - char toLOWER(char ch) + bool isWORDCHAR(char ch) =for hackers Found in file handy.h -=item toUPPER -X<toUPPER> +=item isXDIGIT +X<isXDIGIT> -Converts the specified character to uppercase. Characters outside the -US-ASCII (Basic Latin) range are viewed as not having any case. +Returns a boolean indicating whether the specified character is a hexadecimal +digit, [0-9A-Fa-f]. Variants C<isXDIGIT_A()> and C<isXDIGIT_L1()> are +identical to C<isXDIGIT()>. - char toUPPER(char ch) + bool isXDIGIT(char ch) =for hackers Found in file handy.h @@ -669,6 +762,486 @@ Found in file sv.c =back +=head1 Compile-time scope hooks + +=over 8 + +=item BhkDISABLE +X<BhkDISABLE> + +Temporarily disable an entry in this BHK structure, by clearing the +appropriate flag. I<which> is a preprocessor token indicating which +entry to disable. + +NOTE: this function is experimental and may change or be +removed without notice. + + void BhkDISABLE(BHK *hk, which) + +=for hackers +Found in file op.h + +=item BhkENABLE +X<BhkENABLE> + +Re-enable an entry in this BHK structure, by setting the appropriate +flag. I<which> is a preprocessor token indicating which entry to enable. +This will assert (under -DDEBUGGING) if the entry doesn't contain a valid +pointer. + +NOTE: this function is experimental and may change or be +removed without notice. + + void BhkENABLE(BHK *hk, which) + +=for hackers +Found in file op.h + +=item BhkENTRY_set +X<BhkENTRY_set> + +Set an entry in the BHK structure, and set the flags to indicate it is +valid. I<which> is a preprocessing token indicating which entry to set. +The type of I<ptr> depends on the entry. + +NOTE: this function is experimental and may change or be +removed without notice. + + void BhkENTRY_set(BHK *hk, which, void *ptr) + +=for hackers +Found in file op.h + +=item blockhook_register +X<blockhook_register> + +Register a set of hooks to be called when the Perl lexical scope changes +at compile time. See L<perlguts/"Compile-time scope hooks">. + +NOTE: this function is experimental and may change or be +removed without notice. + +NOTE: this function must be explicitly called as Perl_blockhook_register with an aTHX_ parameter. + + void Perl_blockhook_register(pTHX_ BHK *hk) + +=for hackers +Found in file op.c + + +=back + +=head1 COP Hint Hashes + +=over 8 + +=item cophh_2hv +X<cophh_2hv> + +Generates and returns a standard Perl hash representing the full set of +key/value pairs in the cop hints hash I<cophh>. I<flags> is currently +unused and must be zero. + +NOTE: this function is experimental and may change or be +removed without notice. + + HV * cophh_2hv(const COPHH *cophh, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_copy +X<cophh_copy> + +Make and return a complete copy of the cop hints hash I<cophh>. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_copy(COPHH *cophh) + +=for hackers +Found in file cop.h + +=item cophh_delete_pv +X<cophh_delete_pv> + +Like L</cophh_delete_pvn>, but takes a nul-terminated string instead of +a string/length pair. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_delete_pv(const COPHH *cophh, const char *key, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_delete_pvn +X<cophh_delete_pvn> + +Delete a key and its associated value from the cop hints hash I<cophh>, +and returns the modified hash. The returned hash pointer is in general +not the same as the hash pointer that was passed in. The input hash is +consumed by the function, and the pointer to it must not be subsequently +used. Use L</cophh_copy> if you need both hashes. + +The key is specified by I<keypv> and I<keylen>. If I<flags> has the +C<COPHH_KEY_UTF8> bit set, the key octets are interpreted as UTF-8, +otherwise they are interpreted as Latin-1. I<hash> is a precomputed +hash of the key string, or zero if it has not been precomputed. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_delete_pvn(COPHH *cophh, const char *keypv, STRLEN keylen, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_delete_pvs +X<cophh_delete_pvs> + +Like L</cophh_delete_pvn>, but takes a literal string instead of a +string/length pair, and no precomputed hash. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_delete_pvs(const COPHH *cophh, const char *key, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_delete_sv +X<cophh_delete_sv> + +Like L</cophh_delete_pvn>, but takes a Perl scalar instead of a +string/length pair. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_delete_sv(const COPHH *cophh, SV *key, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_fetch_pv +X<cophh_fetch_pv> + +Like L</cophh_fetch_pvn>, but takes a nul-terminated string instead of +a string/length pair. + +NOTE: this function is experimental and may change or be +removed without notice. + + SV * cophh_fetch_pv(const COPHH *cophh, const char *key, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_fetch_pvn +X<cophh_fetch_pvn> + +Look up the entry in the cop hints hash I<cophh> with the key specified by +I<keypv> and I<keylen>. If I<flags> has the C<COPHH_KEY_UTF8> bit set, +the key octets are interpreted as UTF-8, otherwise they are interpreted +as Latin-1. I<hash> is a precomputed hash of the key string, or zero if +it has not been precomputed. Returns a mortal scalar copy of the value +associated with the key, or C<&PL_sv_placeholder> if there is no value +associated with the key. + +NOTE: this function is experimental and may change or be +removed without notice. + + SV * cophh_fetch_pvn(const COPHH *cophh, const char *keypv, STRLEN keylen, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_fetch_pvs +X<cophh_fetch_pvs> + +Like L</cophh_fetch_pvn>, but takes a literal string instead of a +string/length pair, and no precomputed hash. + +NOTE: this function is experimental and may change or be +removed without notice. + + SV * cophh_fetch_pvs(const COPHH *cophh, const char *key, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_fetch_sv +X<cophh_fetch_sv> + +Like L</cophh_fetch_pvn>, but takes a Perl scalar instead of a +string/length pair. + +NOTE: this function is experimental and may change or be +removed without notice. + + SV * cophh_fetch_sv(const COPHH *cophh, SV *key, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_free +X<cophh_free> + +Discard the cop hints hash I<cophh>, freeing all resources associated +with it. + +NOTE: this function is experimental and may change or be +removed without notice. + + void cophh_free(COPHH *cophh) + +=for hackers +Found in file cop.h + +=item cophh_new_empty +X<cophh_new_empty> + +Generate and return a fresh cop hints hash containing no entries. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_new_empty() + +=for hackers +Found in file cop.h + +=item cophh_store_pv +X<cophh_store_pv> + +Like L</cophh_store_pvn>, but takes a nul-terminated string instead of +a string/length pair. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_store_pv(const COPHH *cophh, const char *key, U32 hash, SV *value, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_store_pvn +X<cophh_store_pvn> + +Stores a value, associated with a key, in the cop hints hash I<cophh>, +and returns the modified hash. The returned hash pointer is in general +not the same as the hash pointer that was passed in. The input hash is +consumed by the function, and the pointer to it must not be subsequently +used. Use L</cophh_copy> if you need both hashes. + +The key is specified by I<keypv> and I<keylen>. If I<flags> has the +C<COPHH_KEY_UTF8> bit set, the key octets are interpreted as UTF-8, +otherwise they are interpreted as Latin-1. I<hash> is a precomputed +hash of the key string, or zero if it has not been precomputed. + +I<value> is the scalar value to store for this key. I<value> is copied +by this function, which thus does not take ownership of any reference +to it, and later changes to the scalar will not be reflected in the +value visible in the cop hints hash. Complex types of scalar will not +be stored with referential integrity, but will be coerced to strings. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv, STRLEN keylen, U32 hash, SV *value, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_store_pvs +X<cophh_store_pvs> + +Like L</cophh_store_pvn>, but takes a literal string instead of a +string/length pair, and no precomputed hash. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_store_pvs(const COPHH *cophh, const char *key, SV *value, U32 flags) + +=for hackers +Found in file cop.h + +=item cophh_store_sv +X<cophh_store_sv> + +Like L</cophh_store_pvn>, but takes a Perl scalar instead of a +string/length pair. + +NOTE: this function is experimental and may change or be +removed without notice. + + COPHH * cophh_store_sv(const COPHH *cophh, SV *key, U32 hash, SV *value, U32 flags) + +=for hackers +Found in file cop.h + + +=back + +=head1 COP Hint Reading + +=over 8 + +=item cop_hints_2hv +X<cop_hints_2hv> + +Generates and returns a standard Perl hash representing the full set of +hint entries in the cop I<cop>. I<flags> is currently unused and must +be zero. + + HV * cop_hints_2hv(const COP *cop, U32 flags) + +=for hackers +Found in file cop.h + +=item cop_hints_fetch_pv +X<cop_hints_fetch_pv> + +Like L</cop_hints_fetch_pvn>, but takes a nul-terminated string instead +of a string/length pair. + + SV * cop_hints_fetch_pv(const COP *cop, const char *key, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + +=item cop_hints_fetch_pvn +X<cop_hints_fetch_pvn> + +Look up the hint entry in the cop I<cop> with the key specified by +I<keypv> and I<keylen>. If I<flags> has the C<COPHH_KEY_UTF8> bit set, +the key octets are interpreted as UTF-8, otherwise they are interpreted +as Latin-1. I<hash> is a precomputed hash of the key string, or zero if +it has not been precomputed. Returns a mortal scalar copy of the value +associated with the key, or C<&PL_sv_placeholder> if there is no value +associated with the key. + + SV * cop_hints_fetch_pvn(const COP *cop, const char *keypv, STRLEN keylen, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + +=item cop_hints_fetch_pvs +X<cop_hints_fetch_pvs> + +Like L</cop_hints_fetch_pvn>, but takes a literal string instead of a +string/length pair, and no precomputed hash. + + SV * cop_hints_fetch_pvs(const COP *cop, const char *key, U32 flags) + +=for hackers +Found in file cop.h + +=item cop_hints_fetch_sv +X<cop_hints_fetch_sv> + +Like L</cop_hints_fetch_pvn>, but takes a Perl scalar instead of a +string/length pair. + + SV * cop_hints_fetch_sv(const COP *cop, SV *key, U32 hash, U32 flags) + +=for hackers +Found in file cop.h + + +=back + +=head1 Custom Operators + +=over 8 + +=item custom_op_register +X<custom_op_register> + +Register a custom op. See L<perlguts/"Custom Operators">. + +NOTE: this function must be explicitly called as Perl_custom_op_register with an aTHX_ parameter. + + void Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr, const XOP *xop) + +=for hackers +Found in file op.c + +=item custom_op_xop +X<custom_op_xop> + +Return the XOP structure for a given custom op. This function should be +considered internal to OP_NAME and the other access macros: use them instead. + +NOTE: this function must be explicitly called as Perl_custom_op_xop with an aTHX_ parameter. + + const XOP * Perl_custom_op_xop(pTHX_ const OP *o) + +=for hackers +Found in file op.c + +=item XopDISABLE +X<XopDISABLE> + +Temporarily disable a member of the XOP, by clearing the appropriate flag. + + void XopDISABLE(XOP *xop, which) + +=for hackers +Found in file op.h + +=item XopENABLE +X<XopENABLE> + +Reenable a member of the XOP which has been disabled. + + void XopENABLE(XOP *xop, which) + +=for hackers +Found in file op.h + +=item XopENTRY +X<XopENTRY> + +Return a member of the XOP structure. I<which> is a cpp token indicating +which entry to return. If the member is not set this will return a +default value. The return type depends on I<which>. + + XopENTRY(XOP *xop, which) + +=for hackers +Found in file op.h + +=item XopENTRY_set +X<XopENTRY_set> + +Set a member of the XOP structure. I<which> is a cpp token indicating +which entry to set. See L<perlguts/"Custom Operators"> for details about +the available members and how they are used. + + void XopENTRY_set(XOP *xop, which, value) + +=for hackers +Found in file op.h + +=item XopFLAGS +X<XopFLAGS> + +Return the XOP's flags. + + U32 XopFLAGS(XOP *xop) + +=for hackers +Found in file op.h + + +=back + =head1 CV Manipulation Functions =over 8 @@ -729,7 +1302,7 @@ children can still follow the full lexical scope chain. void cv_undef(CV* cv) =for hackers -Found in file op.c +Found in file pad.c =item load_module X<load_module> @@ -763,6 +1336,34 @@ no threads. =for hackers Found in file perl.c +=item pad_findmy +X<pad_findmy> + +Given a lexical name, try to find its offset, first in the current pad, +or failing that, in the pads of any lexically enclosing subs (including +the complications introduced by eval). If the name is found in an outer pad, +then a fake entry is added to the current pad. +Returns the offset in the current pad, or NOT_IN_PAD on failure. + +NOTE: this function is experimental and may change or be +removed without notice. + + PADOFFSET pad_findmy(const char* name, STRLEN len, U32 flags) + +=for hackers +Found in file pad.c + +=item pad_sv +X<pad_sv> + +Get the value at offset po in the current pad. +Use macro PAD_SV instead of calling this function directly. + + SV* pad_sv(PADOFFSET po) + +=for hackers +Found in file pad.c + =item perl_alloc X<perl_alloc> @@ -880,18 +1481,18 @@ if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned using C<is_utf8_string()> to determine if it is Unicode. If PERL_PV_ESCAPE_ALL is set then all input chars will be output -using C<\x01F1> style escapes, otherwise only chars above 255 will be -escaped using this style, other non printable chars will use octal or -common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH -then all chars below 255 will be treated as printable and +using C<\x01F1> style escapes, otherwise if PERL_PV_ESCAPE_NONASCII is set, only +chars above 127 will be escaped using this style; otherwise, only chars above +255 will be so escaped; other non printable chars will use octal or +common escaped patterns like C<\n>. Otherwise, if PERL_PV_ESCAPE_NOBACKSLASH +then all chars below 255 will be treated as printable and will be output as literals. If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the -string will be escaped, regardles of max. If the string is utf8 and -the chars value is >255 then it will be returned as a plain hex -sequence. Thus the output will either be a single char, -an octal escape sequence, a special escape like C<\n> or a 3 or -more digit hex value. +string will be escaped, regardless of max. If the output is to be in hex, +then it will be returned as a plain hex +sequence. Thus the output will either be a single char, +an octal escape sequence, a special escape like C<\n> or a hex value. If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and not a '\\'. This is because regexes very often contain backslashed @@ -914,18 +1515,18 @@ If the PERL_PV_PRETTY_QUOTE flag is set then the result will be double quoted with any double quotes in the string escaped. Otherwise if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in angle brackets. - + If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in string were output then an ellipsis C<...> will be appended to the string. Note that this happens AFTER it has been quoted. - + If start_color is non-null then it will be inserted after the opening quote (if there is one) but before the escaped text. If end_color is non-null then it will be inserted after the escaped text but before any quotes or ellipses. Returns a pointer to the prettified text as held by dsv. - + 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 @@ -939,6 +1540,30 @@ Found in file dump.c =over 8 +=item custom_op_desc +X<custom_op_desc> + +Return the description of a given custom op. This was once used by the +OP_DESC macro, but is no longer: it has only been kept for +compatibility, and should not be used. + + const char * custom_op_desc(const OP *o) + +=for hackers +Found in file mathoms.c + +=item custom_op_name +X<custom_op_name> + +Return the name for a given custom op. This was once used by the OP_NAME +macro, but is no longer: it has only been kept for compatibility, and +should not be used. + + const char * custom_op_name(const OP *o) + +=for hackers +Found in file mathoms.c + =item gv_fetchmethod X<gv_fetchmethod> @@ -1212,6 +1837,27 @@ Found in file mathoms.c =back +=head1 Functions in file op.c + + +=over 8 + +=item op_contextualize +X<op_contextualize> + +Applies a syntactic context to an op tree representing an expression. +I<o> is the op tree, and I<context> must be C<G_SCALAR>, C<G_ARRAY>, +or C<G_VOID> to specify the context to apply. The modified op tree +is returned. + + OP * op_contextualize(OP *o, I32 context) + +=for hackers +Found in file op.c + + +=back + =head1 Functions in file perl.h @@ -1261,6 +1907,27 @@ Found in file perl.h =over 8 +=item caller_cx +X<caller_cx> + +The XSUB-writer's equivalent of L<caller()|perlfunc/caller>. The +returned C<PERL_CONTEXT> structure can be interrogated to find all the +information returned to Perl by C<caller>. Note that XSUBs don't get a +stack frame, so C<caller_cx(0, NULL)> will return information for the +immediately-surrounding Perl code. + +This function skips over the automatic calls to C<&DB::sub> made on the +behalf of the debugger. If the stack frame requested was a sub called by +C<DB::sub>, the return value will be the frame for the call to +C<DB::sub>, since that has the correct line number/etc. for the call +site. If I<dbcxp> is non-C<NULL>, it will be set to a pointer to the +frame for the sub call itself. + + const PERL_CONTEXT * caller_cx(I32 level, const PERL_CONTEXT **dbcxp) + +=for hackers +Found in file pp_ctl.c + =item find_runcv X<find_runcv> @@ -1329,6 +1996,52 @@ Found in file pp_sys.c =back +=head1 Functions in file utf8.h + + +=over 8 + +=item ibcmp_utf8 +X<ibcmp_utf8> + +This is a synonym for (! foldEQ_utf8()) + + I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2) + +=for hackers +Found in file utf8.h + + +=back + +=head1 Functions in file util.h + + +=over 8 + +=item ibcmp +X<ibcmp> + +This is a synonym for (! foldEQ()) + + I32 ibcmp(const char* a, const char* b, I32 len) + +=for hackers +Found in file util.h + +=item ibcmp_locale +X<ibcmp_locale> + +This is a synonym for (! foldEQ_locale()) + + I32 ibcmp_locale(const char* a, const char* b, I32 len) + +=for hackers +Found in file util.h + + +=back + =head1 Global Variables =over 8 @@ -1358,7 +2071,7 @@ introduced by the keyword. See L</Lexer interface> for details. When a keyword is being handled, the plugin function must build a tree of C<OP> structures, representing the code that was parsed. The root of the tree must be stored in C<*op_ptr>. The function then -returns a contant indicating the syntactic role of the construct that +returns a constant indicating the syntactic role of the construct that it has parsed: C<KEYWORD_PLUGIN_STMT> if it is a complete statement, or C<KEYWORD_PLUGIN_EXPR> if it is an expression. Note that a statement construct cannot be used inside an expression (except via C<do BLOCK> @@ -1735,6 +2448,21 @@ Returns the value slot (type C<SV*>) stored in the hash entry. =for hackers Found in file hv.h +=item HvENAME +X<HvENAME> + +Returns the effective name of a stash, or NULL if there is none. The +effective name represents a location in the symbol table where this stash +resides. It is updated automatically when packages are aliased or deleted. +A stash that is no longer in the symbol table has no effective name. This +name is preferable to C<HvNAME> for use in MRO linearisations and isa +caches. + + char* HvENAME(HV* stash) + +=for hackers +Found in file hv.h + =item HvNAME X<HvNAME> @@ -1782,13 +2510,27 @@ See Hash::Util::lock_keys() for an example of its use. =for hackers Found in file hv.c +=item hv_copy_hints_hv +X<hv_copy_hints_hv> + +A specialised version of L</newHVhv> for copying C<%^H>. I<ohv> must be +a pointer to a hash (which may have C<%^H> magic, but should be generally +non-magical), or C<NULL> (interpreted as an empty hash). The content +of I<ohv> is copied to a new hash, which has the C<%^H>-specific magic +added to it. A pointer to the new hash is returned. + + HV * hv_copy_hints_hv(HV *ohv) + +=for hackers +Found in file hv.c + =item hv_delete X<hv_delete> -Deletes a key/value pair in the hash. The value SV is removed from the -hash and returned to the caller. The C<klen> is the length of the key. -The C<flags> value will normally be zero; if set to G_DISCARD then NULL -will be returned. +Deletes a key/value pair in the hash. The value's SV is removed from the +hash, made mortal, and returned to the caller. The C<klen> is the length of +the key. The C<flags> value will normally be zero; if set to G_DISCARD then +NULL will be returned. NULL will also be returned if the key is not found. SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags) @@ -1798,10 +2540,11 @@ Found in file hv.c =item hv_delete_ent X<hv_delete_ent> -Deletes a key/value pair in the hash. The value SV is removed from the -hash and returned to the caller. The C<flags> value will normally be zero; -if set to G_DISCARD then NULL will be returned. C<hash> can be a valid -precomputed hash value, or 0 to ask for it to be computed. +Deletes a key/value pair in the hash. The value SV is removed from the hash, +made mortal, and returned to the caller. The C<flags> value will normally be +zero; if set to G_DISCARD then NULL will be returned. NULL will also be +returned if the key is not found. C<hash> can be a valid precomputed hash +value, or 0 to ask for it to be computed. SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash) @@ -1864,7 +2607,7 @@ Returns the hash entry which corresponds to the specified key in the hash. C<hash> must be a valid precomputed hash number for the given C<key>, or 0 if you want the function to compute it. IF C<lval> is set then the fetch will be part of a store. Make sure the return value is non-null before -accessing it. The return value when C<tb> is a tied hash is a pointer to a +accessing it. The return value when C<hv> is a tied hash is a pointer to a static location, so be sure to make a copy of the structure if you need to store it somewhere. @@ -1876,16 +2619,30 @@ information on how to use this function on tied hashes. =for hackers Found in file hv.c +=item hv_fill +X<hv_fill> + +Returns the number of hash buckets that happen to be in use. This function is +wrapped by the macro C<HvFILL>. + +Previously this value was stored in the HV structure, rather than being +calculated on demand. + + STRLEN hv_fill(HV const *const hv) + +=for hackers +Found in file hv.c + =item hv_iterinit X<hv_iterinit> Prepares a starting point to traverse a hash table. Returns the number of -keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is +keys in the hash (i.e. the same as C<HvKEYS(hv)>). The return value is currently only meaningful for hashes without tie magic. NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of hash buckets that happen to be in use. If you still need that esoteric -value, you can get it through the macro C<HvFILL(tb)>. +value, you can get it through the macro C<HvFILL(hv)>. I32 hv_iterinit(HV *hv) @@ -2135,7 +2892,7 @@ it is not permitted to discard text that has yet to be lexed. Normally it is not necessarily to do this directly, because it suffices to use the implicit discarding behaviour of L</lex_next_chunk> and things based on it. However, if a token stretches across multiple lines, -and the lexing code has kept multiple lines of text in the buffer fof +and the lexing code has kept multiple lines of text in the buffer for that purpose, then after completion of the token it would be wise to explicitly discard the now-unneeded earlier lines, to avoid future multi-line tokens growing the buffer without bound. @@ -2288,6 +3045,63 @@ removed without notice. =for hackers Found in file toke.c +=item lex_start +X<lex_start> + +Creates and initialises a new lexer/parser state object, supplying +a context in which to lex and parse from a new source of Perl code. +A pointer to the new state object is placed in L</PL_parser>. An entry +is made on the save stack so that upon unwinding the new state object +will be destroyed and the former value of L</PL_parser> will be restored. +Nothing else need be done to clean up the parsing context. + +The code to be parsed comes from I<line> and I<rsfp>. I<line>, if +non-null, provides a string (in SV form) containing code to be parsed. +A copy of the string is made, so subsequent modification of I<line> +does not affect parsing. I<rsfp>, if non-null, provides an input stream +from which code will be read to be parsed. If both are non-null, the +code in I<line> comes first and must consist of complete lines of input, +and I<rsfp> supplies the remainder of the source. + +The I<flags> parameter is reserved for future use, and must always +be zero, except for one flag that is currently reserved for perl's internal +use. + +NOTE: this function is experimental and may change or be +removed without notice. + + void lex_start(SV *line, PerlIO *rsfp, U32 flags) + +=for hackers +Found in file toke.c + +=item lex_stuff_pv +X<lex_stuff_pv> + +Insert characters into the lexer buffer (L</PL_parser-E<gt>linestr>), +immediately after the current lexing point (L</PL_parser-E<gt>bufptr>), +reallocating the buffer if necessary. This means that lexing code that +runs later will see the characters as if they had appeared in the input. +It is not recommended to do this as part of normal parsing, and most +uses of this facility run the risk of the inserted characters being +interpreted in an unintended manner. + +The string to be inserted is represented by octets starting at I<pv> +and continuing to the first nul. These octets are interpreted as either +UTF-8 or Latin-1, according to whether the C<LEX_STUFF_UTF8> flag is set +in I<flags>. The characters are recoded for the lexer buffer, according +to how the buffer is currently being interpreted (L</lex_bufutf8>). +If it is not convenient to nul-terminate a string to be inserted, the +L</lex_stuff_pvn> function is more appropriate. + +NOTE: this function is experimental and may change or be +removed without notice. + + void lex_stuff_pv(const char *pv, U32 flags) + +=for hackers +Found in file toke.c + =item lex_stuff_pvn X<lex_stuff_pvn> @@ -2304,17 +3118,31 @@ at I<pv>. These octets are interpreted as either UTF-8 or Latin-1, according to whether the C<LEX_STUFF_UTF8> flag is set in I<flags>. The characters are recoded for the lexer buffer, according to how the buffer is currently being interpreted (L</lex_bufutf8>). If a string -to be interpreted is available as a Perl scalar, the L</lex_stuff_sv> +to be inserted is available as a Perl scalar, the L</lex_stuff_sv> function is more convenient. NOTE: this function is experimental and may change or be removed without notice. - void lex_stuff_pvn(char *pv, STRLEN len, U32 flags) + void lex_stuff_pvn(const char *pv, STRLEN len, U32 flags) =for hackers Found in file toke.c +=item lex_stuff_pvs +X<lex_stuff_pvs> + +Like L</lex_stuff_pvn>, but takes a literal string instead of a +string/length pair. + +NOTE: this function is experimental and may change or be +removed without notice. + + void lex_stuff_pvs(const char *pv, U32 flags) + +=for hackers +Found in file handy.h + =item lex_stuff_sv X<lex_stuff_sv> @@ -2328,7 +3156,7 @@ interpreted in an unintended manner. The string to be inserted is the string value of I<sv>. The characters are recoded for the lexer buffer, according to how the buffer is currently -being interpreted (L</lex_bufutf8>). If a string to be interpreted is +being interpreted (L</lex_bufutf8>). If a string to be inserted is not already a Perl scalar, the L</lex_stuff_pvn> function avoids the need to construct a scalar. @@ -2359,6 +3187,291 @@ removed without notice. =for hackers Found in file toke.c +=item parse_arithexpr +X<parse_arithexpr> + +Parse a Perl arithmetic expression. This may contain operators of precedence +down to the bit shift operators. The expression must be followed (and thus +terminated) either by a comparison or lower-precedence operator or by +something that would normally terminate an expression such as semicolon. +If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional, +otherwise it is mandatory. It is up to the caller to ensure that the +dynamic parser state (L</PL_parser> et al) is correctly set to reflect +the source of the code to be parsed and the lexical context for the +expression. + +The op tree representing the expression is returned. If an optional +expression is absent, a null pointer is returned, otherwise the pointer +will be non-null. + +If an error occurs in parsing or compilation, in most cases a valid op +tree is returned anyway. The error is reflected in the parser state, +normally resulting in a single exception at the top level of parsing +which covers all the compilation errors that occurred. Some compilation +errors, however, will throw an exception immediately. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * parse_arithexpr(U32 flags) + +=for hackers +Found in file toke.c + +=item parse_barestmt +X<parse_barestmt> + +Parse a single unadorned Perl statement. This may be a normal imperative +statement or a declaration that has compile-time effect. It does not +include any label or other affixture. It is up to the caller to ensure +that the dynamic parser state (L</PL_parser> et al) is correctly set to +reflect the source of the code to be parsed and the lexical context for +the statement. + +The op tree representing the statement is returned. This may be a +null pointer if the statement is null, for example if it was actually +a subroutine definition (which has compile-time side effects). If not +null, it will be ops directly implementing the statement, suitable to +pass to L</newSTATEOP>. It will not normally include a C<nextstate> or +equivalent op (except for those embedded in a scope contained entirely +within the statement). + +If an error occurs in parsing or compilation, in most cases a valid op +tree (most likely null) is returned anyway. The error is reflected in +the parser state, normally resulting in a single exception at the top +level of parsing which covers all the compilation errors that occurred. +Some compilation errors, however, will throw an exception immediately. + +The I<flags> parameter is reserved for future use, and must always +be zero. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * parse_barestmt(U32 flags) + +=for hackers +Found in file toke.c + +=item parse_block +X<parse_block> + +Parse a single complete Perl code block. This consists of an opening +brace, a sequence of statements, and a closing brace. The block +constitutes a lexical scope, so C<my> variables and various compile-time +effects can be contained within it. It is up to the caller to ensure +that the dynamic parser state (L</PL_parser> et al) is correctly set to +reflect the source of the code to be parsed and the lexical context for +the statement. + +The op tree representing the code block is returned. This is always a +real op, never a null pointer. It will normally be a C<lineseq> list, +including C<nextstate> or equivalent ops. No ops to construct any kind +of runtime scope are included by virtue of it being a block. + +If an error occurs in parsing or compilation, in most cases a valid op +tree (most likely null) is returned anyway. The error is reflected in +the parser state, normally resulting in a single exception at the top +level of parsing which covers all the compilation errors that occurred. +Some compilation errors, however, will throw an exception immediately. + +The I<flags> parameter is reserved for future use, and must always +be zero. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * parse_block(U32 flags) + +=for hackers +Found in file toke.c + +=item parse_fullexpr +X<parse_fullexpr> + +Parse a single complete Perl expression. This allows the full +expression grammar, including the lowest-precedence operators such +as C<or>. The expression must be followed (and thus terminated) by a +token that an expression would normally be terminated by: end-of-file, +closing bracketing punctuation, semicolon, or one of the keywords that +signals a postfix expression-statement modifier. If I<flags> includes +C<PARSE_OPTIONAL> then the expression is optional, otherwise it is +mandatory. It is up to the caller to ensure that the dynamic parser +state (L</PL_parser> et al) is correctly set to reflect the source of +the code to be parsed and the lexical context for the expression. + +The op tree representing the expression is returned. If an optional +expression is absent, a null pointer is returned, otherwise the pointer +will be non-null. + +If an error occurs in parsing or compilation, in most cases a valid op +tree is returned anyway. The error is reflected in the parser state, +normally resulting in a single exception at the top level of parsing +which covers all the compilation errors that occurred. Some compilation +errors, however, will throw an exception immediately. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * parse_fullexpr(U32 flags) + +=for hackers +Found in file toke.c + +=item parse_fullstmt +X<parse_fullstmt> + +Parse a single complete Perl statement. This may be a normal imperative +statement or a declaration that has compile-time effect, and may include +optional labels. It is up to the caller to ensure that the dynamic +parser state (L</PL_parser> et al) is correctly set to reflect the source +of the code to be parsed and the lexical context for the statement. + +The op tree representing the statement is returned. This may be a +null pointer if the statement is null, for example if it was actually +a subroutine definition (which has compile-time side effects). If not +null, it will be the result of a L</newSTATEOP> call, normally including +a C<nextstate> or equivalent op. + +If an error occurs in parsing or compilation, in most cases a valid op +tree (most likely null) is returned anyway. The error is reflected in +the parser state, normally resulting in a single exception at the top +level of parsing which covers all the compilation errors that occurred. +Some compilation errors, however, will throw an exception immediately. + +The I<flags> parameter is reserved for future use, and must always +be zero. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * parse_fullstmt(U32 flags) + +=for hackers +Found in file toke.c + +=item parse_label +X<parse_label> + +Parse a single label, possibly optional, of the type that may prefix a +Perl statement. It is up to the caller to ensure that the dynamic parser +state (L</PL_parser> et al) is correctly set to reflect the source of +the code to be parsed. If I<flags> includes C<PARSE_OPTIONAL> then the +label is optional, otherwise it is mandatory. + +The name of the label is returned in the form of a fresh scalar. If an +optional label is absent, a null pointer is returned. + +If an error occurs in parsing, which can only occur if the label is +mandatory, a valid label is returned anyway. The error is reflected in +the parser state, normally resulting in a single exception at the top +level of parsing which covers all the compilation errors that occurred. + +NOTE: this function is experimental and may change or be +removed without notice. + + SV * parse_label(U32 flags) + +=for hackers +Found in file toke.c + +=item parse_listexpr +X<parse_listexpr> + +Parse a Perl list expression. This may contain operators of precedence +down to the comma operator. The expression must be followed (and thus +terminated) either by a low-precedence logic operator such as C<or> or by +something that would normally terminate an expression such as semicolon. +If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional, +otherwise it is mandatory. It is up to the caller to ensure that the +dynamic parser state (L</PL_parser> et al) is correctly set to reflect +the source of the code to be parsed and the lexical context for the +expression. + +The op tree representing the expression is returned. If an optional +expression is absent, a null pointer is returned, otherwise the pointer +will be non-null. + +If an error occurs in parsing or compilation, in most cases a valid op +tree is returned anyway. The error is reflected in the parser state, +normally resulting in a single exception at the top level of parsing +which covers all the compilation errors that occurred. Some compilation +errors, however, will throw an exception immediately. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * parse_listexpr(U32 flags) + +=for hackers +Found in file toke.c + +=item parse_stmtseq +X<parse_stmtseq> + +Parse a sequence of zero or more Perl statements. These may be normal +imperative statements, including optional labels, or declarations +that have compile-time effect, or any mixture thereof. The statement +sequence ends when a closing brace or end-of-file is encountered in a +place where a new statement could have validly started. It is up to +the caller to ensure that the dynamic parser state (L</PL_parser> et al) +is correctly set to reflect the source of the code to be parsed and the +lexical context for the statements. + +The op tree representing the statement sequence is returned. This may +be a null pointer if the statements were all null, for example if there +were no statements or if there were only subroutine definitions (which +have compile-time side effects). If not null, it will be a C<lineseq> +list, normally including C<nextstate> or equivalent ops. + +If an error occurs in parsing or compilation, in most cases a valid op +tree is returned anyway. The error is reflected in the parser state, +normally resulting in a single exception at the top level of parsing +which covers all the compilation errors that occurred. Some compilation +errors, however, will throw an exception immediately. + +The I<flags> parameter is reserved for future use, and must always +be zero. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * parse_stmtseq(U32 flags) + +=for hackers +Found in file toke.c + +=item parse_termexpr +X<parse_termexpr> + +Parse a Perl term expression. This may contain operators of precedence +down to the assignment operators. The expression must be followed (and thus +terminated) either by a comma or lower-precedence operator or by +something that would normally terminate an expression such as semicolon. +If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional, +otherwise it is mandatory. It is up to the caller to ensure that the +dynamic parser state (L</PL_parser> et al) is correctly set to reflect +the source of the code to be parsed and the lexical context for the +expression. + +The op tree representing the expression is returned. If an optional +expression is absent, a null pointer is returned, otherwise the pointer +will be non-null. + +If an error occurs in parsing or compilation, in most cases a valid op +tree is returned anyway. The error is reflected in the parser state, +normally resulting in a single exception at the top level of parsing +which covers all the compilation errors that occurred. Some compilation +errors, however, will throw an exception immediately. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * parse_termexpr(U32 flags) + +=for hackers +Found in file toke.c + =item PL_parser X<PL_parser> @@ -2495,6 +3608,17 @@ Finds the magic pointer for type matching the SV. See C<sv_magic>. =for hackers Found in file mg.c +=item mg_findext +X<mg_findext> + +Finds the magic pointer of C<type> with the given C<vtbl> for the C<SV>. See +C<sv_magicext>. + + MAGIC* mg_findext(const SV* sv, int type, const MGVTBL *vtbl) + +=for hackers +Found in file mg.c + =item mg_free X<mg_free> @@ -2505,6 +3629,16 @@ Free any magic storage used by the SV. See C<sv_magic>. =for hackers Found in file mg.c +=item mg_free_type +X<mg_free_type> + +Remove any magic of type I<how> from the SV I<sv>. See L</sv_magic>. + + void mg_free_type(SV *sv, int how) + +=for hackers +Found in file mg.c + =item mg_get X<mg_get> @@ -2864,6 +3998,28 @@ pointer is not acceptable) =for hackers Found in file util.c +=item savesharedpvs +X<savesharedpvs> + +A version of C<savepvs()> which allocates the duplicate string in memory +which is shared between threads. + + char* savesharedpvs(const char* s) + +=for hackers +Found in file handy.h + +=item savesharedsvpv +X<savesharedsvpv> + +A version of C<savesharedpv()> which allocates the duplicate string in +memory which is shared between threads. + + char* savesharedsvpv(SV *sv) + +=for hackers +Found in file util.c + =item savesvpv X<savesvpv> @@ -2938,6 +4094,30 @@ then. =for hackers Found in file util.c +=item foldEQ +X<foldEQ> + +Returns true if the leading len bytes of the strings s1 and s2 are the same +case-insensitively; false otherwise. Uppercase and lowercase ASCII range bytes +match themselves and their opposite case counterparts. Non-cased and non-ASCII +range bytes match only themselves. + + I32 foldEQ(const char* a, const char* b, I32 len) + +=for hackers +Found in file util.c + +=item foldEQ_locale +X<foldEQ_locale> + +Returns true if the leading len bytes of the strings s1 and s2 are the same +case-insensitively in the current locale; false otherwise. + + I32 foldEQ_locale(const char* a, const char* b, I32 len) + +=for hackers +Found in file util.c + =item form X<form> @@ -2969,6 +4149,49 @@ Fill the sv with current working directory =for hackers Found in file util.c +=item mess +X<mess> + +Take a sprintf-style format pattern and argument list. These are used to +generate a string message. If the message does not end with a newline, +then it will be extended with some indication of the current location +in the code, as described for L</mess_sv>. + +Normally, the resulting message is returned in a new mortal SV. +During global destruction a single SV may be shared between uses of +this function. + + SV * mess(const char *pat, ...) + +=for hackers +Found in file util.c + +=item mess_sv +X<mess_sv> + +Expands a message, intended for the user, to include an indication of +the current location in the code, if the message does not already appear +to be complete. + +C<basemsg> is the initial message or object. If it is a reference, it +will be used as-is and will be the result of this function. Otherwise it +is used as a string, and if it already ends with a newline, it is taken +to be complete, and the result of this function will be the same string. +If the message does not end with a newline, then a segment such as C<at +foo.pl line 37> will be appended, and possibly other clauses indicating +the current state of execution. The resulting message will end with a +dot and a newline. + +Normally, the resulting message is returned in a new mortal SV. +During global destruction a single SV may be shared between uses of this +function. If C<consume> is true, then the function is permitted (but not +required) to modify and return C<basemsg> instead of allocating a new SV. + + SV * mess_sv(SV *basemsg, bool consume) + +=for hackers +Found in file util.c + =item my_snprintf X<my_snprintf> @@ -3028,6 +4251,11 @@ Found in file util.c =item prescan_version X<prescan_version> +Validate that a given string can be parsed as a version object, but doesn't +actually perform the parsing. Can use either strict or lax validation rules. +Can optionally set a number of hint variables to save the parsing code +some time when tokenizing. + const char* prescan_version(const char *s, bool strict, const char** errstr, bool *sqv, int *ssaw_decimal, int *swidth, bool *salpha) =for hackers @@ -3198,6 +4426,24 @@ converted into version objects. =for hackers Found in file util.c +=item vmess +X<vmess> + +C<pat> and C<args> are a sprintf-style format pattern and encapsulated +argument list. These are used to generate a string message. If the +message does not end with a newline, then it will be extended with +some indication of the current location in the code, as described for +L</mess_sv>. + +Normally, the resulting message is returned in a new mortal SV. +During global destruction a single SV may be shared between uses of +this function. + + SV * vmess(const char *pat, va_list *args) + +=for hackers +Found in file util.c + =item vnormal X<vnormal> @@ -3209,6 +4455,8 @@ representation. Call like: NOTE: you can pass either the object directly or the SV contained within the RV. +The SV returned has a refcount of 1. + SV* vnormal(SV *vs) =for hackers @@ -3225,6 +4473,8 @@ point representation. Call like: NOTE: you can pass either the object directly or the SV contained within the RV. +The SV returned has a refcount of 1. + SV* vnumify(SV *vs) =for hackers @@ -3236,7 +4486,9 @@ X<vstringify> In order to maintain maximum compatibility with earlier versions of Perl, this function will return either the floating point notation or the multiple dotted notation, depending on whether -the original version contained 1 or more dots, respectively +the original version contained 1 or more dots, respectively. + +The SV returned has a refcount of 1. SV* vstringify(SV *vs) @@ -3246,14 +4498,17 @@ Found in file util.c =item vverify X<vverify> -Validates that the SV contains a valid version object. +Validates that the SV contains valid internal structure for a version object. +It may be passed either the version object (RV) or the hash itself (HV). If +the structure is valid, it returns the HV. If the structure is invalid, +it returns NULL. - bool vverify(SV *vobj); + SV *hv = vverify(sv); Note that it only confirms the bare minimum structure (so as not to get confused by derived classes which may contain additional hash entries): - bool vverify(SV *vs) + SV* vverify(SV *vs) =for hackers Found in file util.c @@ -3477,7 +4732,7 @@ On entry I<start> and I<*len> give the string to scan, I<*flags> gives conversion flags, and I<result> should be NULL or a pointer to an NV. The scan stops at the end of the string, or the first invalid character. Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an -invalid character will also trigger a warning. +8 or 9 will also trigger a warning. On return I<*len> is set to the length of the scanned string, and I<*flags> gives output flags. @@ -3559,10 +4814,451 @@ Found in file numeric.c =back +=head1 Optree construction + +=over 8 + +=item newASSIGNOP +X<newASSIGNOP> + +Constructs, checks, and returns an assignment op. I<left> and I<right> +supply the parameters of the assignment; they are consumed by this +function and become part of the constructed op tree. + +If I<optype> is C<OP_ANDASSIGN>, C<OP_ORASSIGN>, or C<OP_DORASSIGN>, then +a suitable conditional optree is constructed. If I<optype> is the opcode +of a binary operator, such as C<OP_BIT_OR>, then an op is constructed that +performs the binary operation and assigns the result to the left argument. +Either way, if I<optype> is non-zero then I<flags> has no effect. + +If I<optype> is zero, then a plain scalar or list assignment is +constructed. Which type of assignment it is is automatically determined. +I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS> +will be set automatically, and, shifted up eight bits, the eight bits +of C<op_private>, except that the bit with value 1 or 2 is automatically +set as required. + + OP * newASSIGNOP(I32 flags, OP *left, I32 optype, OP *right) + +=for hackers +Found in file op.c + +=item newBINOP +X<newBINOP> + +Constructs, checks, and returns an op of any binary type. I<type> +is the opcode. I<flags> gives the eight bits of C<op_flags>, except +that C<OPf_KIDS> will be set automatically, and, shifted up eight bits, +the eight bits of C<op_private>, except that the bit with value 1 or +2 is automatically set as required. I<first> and I<last> supply up to +two ops to be the direct children of the binary op; they are consumed +by this function and become part of the constructed op tree. + + OP * newBINOP(I32 type, I32 flags, OP *first, OP *last) + +=for hackers +Found in file op.c + +=item newCONDOP +X<newCONDOP> + +Constructs, checks, and returns a conditional-expression (C<cond_expr>) +op. I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS> +will be set automatically, and, shifted up eight bits, the eight bits of +C<op_private>, except that the bit with value 1 is automatically set. +I<first> supplies the expression selecting between the two branches, +and I<trueop> and I<falseop> supply the branches; they are consumed by +this function and become part of the constructed op tree. + + OP * newCONDOP(I32 flags, OP *first, OP *trueop, OP *falseop) + +=for hackers +Found in file op.c + +=item newFOROP +X<newFOROP> + +Constructs, checks, and returns an op tree expressing a C<foreach> +loop (iteration through a list of values). This is a heavyweight loop, +with structure that allows exiting the loop by C<last> and suchlike. + +I<sv> optionally supplies the variable that will be aliased to each +item in turn; if null, it defaults to C<$_> (either lexical or global). +I<expr> supplies the list of values to iterate over. I<block> supplies +the main body of the loop, and I<cont> optionally supplies a C<continue> +block that operates as a second half of the body. All of these optree +inputs are consumed by this function and become part of the constructed +op tree. + +I<flags> gives the eight bits of C<op_flags> for the C<leaveloop> +op and, shifted up eight bits, the eight bits of C<op_private> for +the C<leaveloop> op, except that (in both cases) some bits will be set +automatically. + + OP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block, OP *cont) + +=for hackers +Found in file op.c + +=item newGIVENOP +X<newGIVENOP> + +Constructs, checks, and returns an op tree expressing a C<given> block. +I<cond> supplies the expression that will be locally assigned to a lexical +variable, and I<block> supplies the body of the C<given> construct; they +are consumed by this function and become part of the constructed op tree. +I<defsv_off> is the pad offset of the scalar lexical variable that will +be affected. + + OP * newGIVENOP(OP *cond, OP *block, PADOFFSET defsv_off) + +=for hackers +Found in file op.c + +=item newGVOP +X<newGVOP> + +Constructs, checks, and returns an op of any type that involves an +embedded reference to a GV. I<type> is the opcode. I<flags> gives the +eight bits of C<op_flags>. I<gv> identifies the GV that the op should +reference; calling this function does not transfer ownership of any +reference to it. + + OP * newGVOP(I32 type, I32 flags, GV *gv) + +=for hackers +Found in file op.c + +=item newLISTOP +X<newLISTOP> + +Constructs, checks, and returns an op of any list type. I<type> is +the opcode. I<flags> gives the eight bits of C<op_flags>, except that +C<OPf_KIDS> will be set automatically if required. I<first> and I<last> +supply up to two ops to be direct children of the list op; they are +consumed by this function and become part of the constructed op tree. + + OP * newLISTOP(I32 type, I32 flags, OP *first, OP *last) + +=for hackers +Found in file op.c + +=item newLOGOP +X<newLOGOP> + +Constructs, checks, and returns a logical (flow control) op. I<type> +is the opcode. I<flags> gives the eight bits of C<op_flags>, except +that C<OPf_KIDS> will be set automatically, and, shifted up eight bits, +the eight bits of C<op_private>, except that the bit with value 1 is +automatically set. I<first> supplies the expression controlling the +flow, and I<other> supplies the side (alternate) chain of ops; they are +consumed by this function and become part of the constructed op tree. + + OP * newLOGOP(I32 type, I32 flags, OP *first, OP *other) + +=for hackers +Found in file op.c + +=item newLOOPEX +X<newLOOPEX> + +Constructs, checks, and returns a loop-exiting op (such as C<goto> +or C<last>). I<type> is the opcode. I<label> supplies the parameter +determining the target of the op; it is consumed by this function and +become part of the constructed op tree. + + OP * newLOOPEX(I32 type, OP *label) + +=for hackers +Found in file op.c + +=item newLOOPOP +X<newLOOPOP> + +Constructs, checks, and returns an op tree expressing a loop. This is +only a loop in the control flow through the op tree; it does not have +the heavyweight loop structure that allows exiting the loop by C<last> +and suchlike. I<flags> gives the eight bits of C<op_flags> for the +top-level op, except that some bits will be set automatically as required. +I<expr> supplies the expression controlling loop iteration, and I<block> +supplies the body of the loop; they are consumed by this function and +become part of the constructed op tree. I<debuggable> is currently +unused and should always be 1. + + OP * newLOOPOP(I32 flags, I32 debuggable, OP *expr, OP *block) + +=for hackers +Found in file op.c + +=item newNULLLIST +X<newNULLLIST> + +Constructs, checks, and returns a new C<stub> op, which represents an +empty list expression. + + OP * newNULLLIST() + +=for hackers +Found in file op.c + +=item newOP +X<newOP> + +Constructs, checks, and returns an op of any base type (any type that +has no extra fields). I<type> is the opcode. I<flags> gives the +eight bits of C<op_flags>, and, shifted up eight bits, the eight bits +of C<op_private>. + + OP * newOP(I32 type, I32 flags) + +=for hackers +Found in file op.c + +=item newPADOP +X<newPADOP> + +Constructs, checks, and returns an op of any type that involves a +reference to a pad element. I<type> is the opcode. I<flags> gives the +eight bits of C<op_flags>. A pad slot is automatically allocated, and +is populated with I<sv>; this function takes ownership of one reference +to it. + +This function only exists if Perl has been compiled to use ithreads. + + OP * newPADOP(I32 type, I32 flags, SV *sv) + +=for hackers +Found in file op.c + +=item newPMOP +X<newPMOP> + +Constructs, checks, and returns an op of any pattern matching type. +I<type> is the opcode. I<flags> gives the eight bits of C<op_flags> +and, shifted up eight bits, the eight bits of C<op_private>. + + OP * newPMOP(I32 type, I32 flags) + +=for hackers +Found in file op.c + +=item newPVOP +X<newPVOP> + +Constructs, checks, and returns an op of any type that involves an +embedded C-level pointer (PV). I<type> is the opcode. I<flags> gives +the eight bits of C<op_flags>. I<pv> supplies the C-level pointer, which +must have been allocated using L</PerlMemShared_malloc>; the memory will +be freed when the op is destroyed. + + OP * newPVOP(I32 type, I32 flags, char *pv) + +=for hackers +Found in file op.c + +=item newRANGE +X<newRANGE> + +Constructs and returns a C<range> op, with subordinate C<flip> and +C<flop> ops. I<flags> gives the eight bits of C<op_flags> for the +C<flip> op and, shifted up eight bits, the eight bits of C<op_private> +for both the C<flip> and C<range> ops, except that the bit with value +1 is automatically set. I<left> and I<right> supply the expressions +controlling the endpoints of the range; they are consumed by this function +and become part of the constructed op tree. + + OP * newRANGE(I32 flags, OP *left, OP *right) + +=for hackers +Found in file op.c + +=item newSLICEOP +X<newSLICEOP> + +Constructs, checks, and returns an C<lslice> (list slice) op. I<flags> +gives the eight bits of C<op_flags>, except that C<OPf_KIDS> will +be set automatically, and, shifted up eight bits, the eight bits of +C<op_private>, except that the bit with value 1 or 2 is automatically +set as required. I<listval> and I<subscript> supply the parameters of +the slice; they are consumed by this function and become part of the +constructed op tree. + + OP * newSLICEOP(I32 flags, OP *subscript, OP *listval) + +=for hackers +Found in file op.c + +=item newSTATEOP +X<newSTATEOP> + +Constructs a state op (COP). The state op is normally a C<nextstate> op, +but will be a C<dbstate> op if debugging is enabled for currently-compiled +code. The state op is populated from L</PL_curcop> (or L</PL_compiling>). +If I<label> is non-null, it supplies the name of a label to attach to +the state op; this function takes ownership of the memory pointed at by +I<label>, and will free it. I<flags> gives the eight bits of C<op_flags> +for the state op. + +If I<o> is null, the state op is returned. Otherwise the state op is +combined with I<o> into a C<lineseq> list op, which is returned. I<o> +is consumed by this function and becomes part of the returned op tree. + + OP * newSTATEOP(I32 flags, char *label, OP *o) + +=for hackers +Found in file op.c + +=item newSVOP +X<newSVOP> + +Constructs, checks, and returns an op of any type that involves an +embedded SV. I<type> is the opcode. I<flags> gives the eight bits +of C<op_flags>. I<sv> gives the SV to embed in the op; this function +takes ownership of one reference to it. + + OP * newSVOP(I32 type, I32 flags, SV *sv) + +=for hackers +Found in file op.c + +=item newUNOP +X<newUNOP> + +Constructs, checks, and returns an op of any unary type. I<type> is +the opcode. I<flags> gives the eight bits of C<op_flags>, except that +C<OPf_KIDS> will be set automatically if required, and, shifted up eight +bits, the eight bits of C<op_private>, except that the bit with value 1 +is automatically set. I<first> supplies an optional op to be the direct +child of the unary op; it is consumed by this function and become part +of the constructed op tree. + + OP * newUNOP(I32 type, I32 flags, OP *first) + +=for hackers +Found in file op.c + +=item newWHENOP +X<newWHENOP> + +Constructs, checks, and returns an op tree expressing a C<when> block. +I<cond> supplies the test expression, and I<block> supplies the block +that will be executed if the test evaluates to true; they are consumed +by this function and become part of the constructed op tree. I<cond> +will be interpreted DWIMically, often as a comparison against C<$_>, +and may be null to generate a C<default> block. + + OP * newWHENOP(OP *cond, OP *block) + +=for hackers +Found in file op.c + +=item newWHILEOP +X<newWHILEOP> + +Constructs, checks, and returns an op tree expressing a C<while> loop. +This is a heavyweight loop, with structure that allows exiting the loop +by C<last> and suchlike. + +I<loop> is an optional preconstructed C<enterloop> op to use in the +loop; if it is null then a suitable op will be constructed automatically. +I<expr> supplies the loop's controlling expression. I<block> supplies the +main body of the loop, and I<cont> optionally supplies a C<continue> block +that operates as a second half of the body. All of these optree inputs +are consumed by this function and become part of the constructed op tree. + +I<flags> gives the eight bits of C<op_flags> for the C<leaveloop> +op and, shifted up eight bits, the eight bits of C<op_private> for +the C<leaveloop> op, except that (in both cases) some bits will be set +automatically. I<debuggable> is currently unused and should always be 1. +I<has_my> can be supplied as true to force the +loop body to be enclosed in its own scope. + + OP * newWHILEOP(I32 flags, I32 debuggable, LOOP *loop, OP *expr, OP *block, OP *cont, I32 has_my) + +=for hackers +Found in file op.c + + +=back + =head1 Optree Manipulation Functions =over 8 +=item ck_entersub_args_list +X<ck_entersub_args_list> + +Performs the default fixup of the arguments part of an C<entersub> +op tree. This consists of applying list context to each of the +argument ops. This is the standard treatment used on a call marked +with C<&>, or a method call, or a call through a subroutine reference, +or any other call where the callee can't be identified at compile time, +or a call where the callee has no prototype. + + OP * ck_entersub_args_list(OP *entersubop) + +=for hackers +Found in file op.c + +=item ck_entersub_args_proto +X<ck_entersub_args_proto> + +Performs the fixup of the arguments part of an C<entersub> op tree +based on a subroutine prototype. This makes various modifications to +the argument ops, from applying context up to inserting C<refgen> ops, +and checking the number and syntactic types of arguments, as directed by +the prototype. This is the standard treatment used on a subroutine call, +not marked with C<&>, where the callee can be identified at compile time +and has a prototype. + +I<protosv> supplies the subroutine prototype to be applied to the call. +It may be a normal defined scalar, of which the string value will be used. +Alternatively, for convenience, it may be a subroutine object (a C<CV*> +that has been cast to C<SV*>) which has a prototype. The prototype +supplied, in whichever form, does not need to match the actual callee +referenced by the op tree. + +If the argument ops disagree with the prototype, for example by having +an unacceptable number of arguments, a valid op tree is returned anyway. +The error is reflected in the parser state, normally resulting in a single +exception at the top level of parsing which covers all the compilation +errors that occurred. In the error message, the callee is referred to +by the name defined by the I<namegv> parameter. + + OP * ck_entersub_args_proto(OP *entersubop, GV *namegv, SV *protosv) + +=for hackers +Found in file op.c + +=item ck_entersub_args_proto_or_list +X<ck_entersub_args_proto_or_list> + +Performs the fixup of the arguments part of an C<entersub> op tree either +based on a subroutine prototype or using default list-context processing. +This is the standard treatment used on a subroutine call, not marked +with C<&>, where the callee can be identified at compile time. + +I<protosv> supplies the subroutine prototype to be applied to the call, +or indicates that there is no prototype. It may be a normal scalar, +in which case if it is defined then the string value will be used +as a prototype, and if it is undefined then there is no prototype. +Alternatively, for convenience, it may be a subroutine object (a C<CV*> +that has been cast to C<SV*>), of which the prototype will be used if it +has one. The prototype (or lack thereof) supplied, in whichever form, +does not need to match the actual callee referenced by the op tree. + +If the argument ops disagree with the prototype, for example by having +an unacceptable number of arguments, a valid op tree is returned anyway. +The error is reflected in the parser state, normally resulting in a single +exception at the top level of parsing which covers all the compilation +errors that occurred. In the error message, the callee is referred to +by the name defined by the I<namegv> parameter. + + OP * ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv, SV *protosv) + +=for hackers +Found in file op.c + =item cv_const_sv X<cv_const_sv> @@ -3577,6 +5273,81 @@ L<perlsub/"Constant Functions">. =for hackers Found in file op.c +=item cv_get_call_checker +X<cv_get_call_checker> + +Retrieves the function that will be used to fix up a call to I<cv>. +Specifically, the function is applied to an C<entersub> op tree for a +subroutine call, not marked with C<&>, where the callee can be identified +at compile time as I<cv>. + +The C-level function pointer is returned in I<*ckfun_p>, and an SV +argument for it is returned in I<*ckobj_p>. The function is intended +to be called in this manner: + + entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p)); + +In this call, I<entersubop> is a pointer to the C<entersub> op, +which may be replaced by the check function, and I<namegv> is a GV +supplying the name that should be used by the check function to refer +to the callee of the C<entersub> op if it needs to emit any diagnostics. +It is permitted to apply the check function in non-standard situations, +such as to a call to a different subroutine or to a method call. + +By default, the function is +L<Perl_ck_entersub_args_proto_or_list|/ck_entersub_args_proto_or_list>, +and the SV parameter is I<cv> itself. This implements standard +prototype processing. It can be changed, for a particular subroutine, +by L</cv_set_call_checker>. + + void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p, SV **ckobj_p) + +=for hackers +Found in file op.c + +=item cv_set_call_checker +X<cv_set_call_checker> + +Sets the function that will be used to fix up a call to I<cv>. +Specifically, the function is applied to an C<entersub> op tree for a +subroutine call, not marked with C<&>, where the callee can be identified +at compile time as I<cv>. + +The C-level function pointer is supplied in I<ckfun>, and an SV argument +for it is supplied in I<ckobj>. The function is intended to be called +in this manner: + + entersubop = ckfun(aTHX_ entersubop, namegv, ckobj); + +In this call, I<entersubop> is a pointer to the C<entersub> op, +which may be replaced by the check function, and I<namegv> is a GV +supplying the name that should be used by the check function to refer +to the callee of the C<entersub> op if it needs to emit any diagnostics. +It is permitted to apply the check function in non-standard situations, +such as to a call to a different subroutine or to a method call. + +The current setting for a particular CV can be retrieved by +L</cv_get_call_checker>. + + void cv_set_call_checker(CV *cv, Perl_call_checker ckfun, SV *ckobj) + +=for hackers +Found in file op.c + +=item LINKLIST +X<LINKLIST> + +Given the root of an optree, link the tree in execution order using the +C<op_next> pointers and return the first op executed. If this has +already been done, it will not be redone, and C<< o->op_next >> will be +returned. If C<< o->op_next >> is not already set, I<o> should be at +least an C<UNOP>. + + OP* LINKLIST(OP *o) + +=for hackers +Found in file op.h + =item newCONSTSUB X<newCONSTSUB> @@ -3602,40 +5373,181 @@ static storage, as it is used directly as CvFILE(), without a copy being made. =for hackers Found in file op.c +=item op_append_elem +X<op_append_elem> -=back +Append an item to the list of ops contained directly within a list-type +op, returning the lengthened list. I<first> is the list-type op, +and I<last> is the op to append to the list. I<optype> specifies the +intended opcode for the list. If I<first> is not already a list of the +right type, it will be upgraded into one. If either I<first> or I<last> +is null, the other is returned unchanged. -=head1 Pad Data Structures + OP * op_append_elem(I32 optype, OP *first, OP *last) -=over 8 +=for hackers +Found in file op.c -=item pad_findmy -X<pad_findmy> +=item op_append_list +X<op_append_list> -Given a lexical name, try to find its offset, first in the current pad, -or failing that, in the pads of any lexically enclosing subs (including -the complications introduced by eval). If the name is found in an outer pad, -then a fake entry is added to the current pad. -Returns the offset in the current pad, or NOT_IN_PAD on failure. +Concatenate the lists of ops contained directly within two list-type ops, +returning the combined list. I<first> and I<last> are the list-type ops +to concatenate. I<optype> specifies the intended opcode for the list. +If either I<first> or I<last> is not already a list of the right type, +it will be upgraded into one. If either I<first> or I<last> is null, +the other is returned unchanged. + + OP * op_append_list(I32 optype, OP *first, OP *last) + +=for hackers +Found in file op.c + +=item OP_CLASS +X<OP_CLASS> + +Return the class of the provided OP: that is, which of the *OP +structures it uses. For core ops this currently gets the information out +of PL_opargs, which does not always accurately reflect the type used. +For custom ops the type is returned from the registration, and it is up +to the registree to ensure it is accurate. The value returned will be +one of the OA_* constants from op.h. + + U32 OP_CLASS(OP *o) + +=for hackers +Found in file op.h + +=item OP_DESC +X<OP_DESC> + +Return a short description of the provided OP. + + const char * OP_DESC(OP *o) + +=for hackers +Found in file op.h + +=item op_linklist +X<op_linklist> + +This function is the implementation of the L</LINKLIST> macro. It should +not be called directly. + + OP* op_linklist(OP *o) + +=for hackers +Found in file op.c + +=item op_lvalue +X<op_lvalue> + +Propagate lvalue ("modifiable") context to an op and its children. +I<type> represents the context type, roughly based on the type of op that +would do the modifying, although C<local()> is represented by OP_NULL, +because it has no op type of its own (it is signalled by a flag on +the lvalue op). + +This function detects things that can't be modified, such as C<$x+1>, and +generates errors for them. For example, C<$x+1 = 2> would cause it to be +called with an op of type OP_ADD and a C<type> argument of OP_SASSIGN. + +It also flags things that need to behave specially in an lvalue context, +such as C<$$x = 5> which might have to vivify a reference in C<$x>. NOTE: this function is experimental and may change or be removed without notice. - PADOFFSET pad_findmy(const char* name, STRLEN len, U32 flags) + OP * op_lvalue(OP *o, I32 type) =for hackers -Found in file pad.c +Found in file op.c -=item pad_sv -X<pad_sv> +=item OP_NAME +X<OP_NAME> -Get the value at offset po in the current pad. -Use macro PAD_SV instead of calling this function directly. +Return the name of the provided OP. For core ops this looks up the name +from the op_type; for custom ops from the op_ppaddr. - SV* pad_sv(PADOFFSET po) + const char * OP_NAME(OP *o) =for hackers -Found in file pad.c +Found in file op.h + +=item op_prepend_elem +X<op_prepend_elem> + +Prepend an item to the list of ops contained directly within a list-type +op, returning the lengthened list. I<first> is the op to prepend to the +list, and I<last> is the list-type op. I<optype> specifies the intended +opcode for the list. If I<last> is not already a list of the right type, +it will be upgraded into one. If either I<first> or I<last> is null, +the other is returned unchanged. + + OP * op_prepend_elem(I32 optype, OP *first, OP *last) + +=for hackers +Found in file op.c + +=item op_scope +X<op_scope> + +Wraps up an op tree with some additional ops so that at runtime a dynamic +scope will be created. The original ops run in the new dynamic scope, +and then, provided that they exit normally, the scope will be unwound. +The additional ops used to create and unwind the dynamic scope will +normally be an C<enter>/C<leave> pair, but a C<scope> op may be used +instead if the ops are simple enough to not need the full dynamic scope +structure. + +NOTE: this function is experimental and may change or be +removed without notice. + + OP * op_scope(OP *o) + +=for hackers +Found in file op.c + +=item rv2cv_op_cv +X<rv2cv_op_cv> + +Examines an op, which is expected to identify a subroutine at runtime, +and attempts to determine at compile time which subroutine it identifies. +This is normally used during Perl compilation to determine whether +a prototype can be applied to a function call. I<cvop> is the op +being considered, normally an C<rv2cv> op. A pointer to the identified +subroutine is returned, if it could be determined statically, and a null +pointer is returned if it was not possible to determine statically. + +Currently, the subroutine can be identified statically if the RV that the +C<rv2cv> is to operate on is provided by a suitable C<gv> or C<const> op. +A C<gv> op is suitable if the GV's CV slot is populated. A C<const> op is +suitable if the constant value must be an RV pointing to a CV. Details of +this process may change in future versions of Perl. If the C<rv2cv> op +has the C<OPpENTERSUB_AMPER> flag set then no attempt is made to identify +the subroutine statically: this flag is used to suppress compile-time +magic on a subroutine call, forcing it to use default runtime behaviour. + +If I<flags> has the bit C<RV2CVOPCV_MARK_EARLY> set, then the handling +of a GV reference is modified. If a GV was examined and its CV slot was +found to be empty, then the C<gv> op has the C<OPpEARLY_CV> flag set. +If the op is not optimised away, and the CV slot is later populated with +a subroutine having a prototype, that flag eventually triggers the warning +"called too early to check prototype". + +If I<flags> has the bit C<RV2CVOPCV_RETURN_NAME_GV> set, then instead +of returning a pointer to the subroutine it returns a pointer to the +GV giving the most appropriate name for the subroutine in this context. +Normally this is just the C<CvGV> of the subroutine, but for an anonymous +(C<CvANON>) subroutine that is referenced through a GV it will be the +referencing GV. The resulting C<GV*> is cast to C<CV*> to be returned. +A null pointer is returned as usual if there is no statically-determinable +subroutine. + + CV * rv2cv_op_cv(OP *cvop, U32 flags) + +=for hackers +Found in file op.c =back @@ -3685,6 +5597,53 @@ When you replace this variable, it is considered a good practice to store the po =for hackers Found in file intrpvar.h +=item PL_peepp +X<PL_peepp> + +Pointer to the per-subroutine peephole optimiser. This is a function +that gets called at the end of compilation of a Perl subroutine (or +equivalently independent piece of Perl code) to perform fixups of +some ops and to perform small-scale optimisations. The function is +called once for each subroutine that is compiled, and is passed, as sole +parameter, a pointer to the op that is the entry point to the subroutine. +It modifies the op tree in place. + +The peephole optimiser should never be completely replaced. Rather, +add code to it by wrapping the existing optimiser. The basic way to do +this can be seen in L<perlguts/Compile pass 3: peephole optimization>. +If the new code wishes to operate on ops throughout the subroutine's +structure, rather than just at the top level, it is likely to be more +convenient to wrap the L</PL_rpeepp> hook. + + peep_t PL_peepp + +=for hackers +Found in file intrpvar.h + +=item PL_rpeepp +X<PL_rpeepp> + +Pointer to the recursive peephole optimiser. This is a function +that gets called at the end of compilation of a Perl subroutine (or +equivalently independent piece of Perl code) to perform fixups of some +ops and to perform small-scale optimisations. The function is called +once for each chain of ops linked through their C<op_next> fields; +it is recursively called to handle each side chain. It is passed, as +sole parameter, a pointer to the op that is at the head of the chain. +It modifies the op tree in place. + +The peephole optimiser should never be completely replaced. Rather, +add code to it by wrapping the existing optimiser. The basic way to do +this can be seen in L<perlguts/Compile pass 3: peephole optimization>. +If the new code wishes to operate only on ops at a subroutine's top level, +rather than throughout the structure, it is likely to be more convenient +to wrap the L</PL_peepp> hook. + + peep_t PL_rpeepp + +=for hackers +Found in file intrpvar.h + =item PL_sv_no X<PL_sv_no> @@ -3732,13 +5691,10 @@ equivalent to the following snippet: if (SvMAGICAL(sv)) mg_get(sv); - if (SvROK(sv) && - (tmpsv = (SV*)SvRV(sv)) && - SvTYPE(tmpsv) == SVt_PVMG && - (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr))) - { - return (REGEXP *)tmpmg->mg_obj; - } + if (SvROK(sv)) + sv = MUTABLE_SV(SvRV(sv)); + if (SvTYPE(sv) == SVt_REGEXP) + return (REGEXP*) sv; NULL will be returned if a REGEXP* is not found. @@ -3750,8 +5706,8 @@ Found in file regexp.h =item SvRXOK X<SvRXOK> -Returns a boolean indicating whether the SV contains qr magic -(PERL_MAGIC_qr). +Returns a boolean indicating whether the SV (or the one it references) +is a REGEXP. If you want to do something with the REGEXP* later use SvRX instead and check for NULL. @@ -4505,7 +6461,7 @@ A specialised variant of C<croak()> for emitting the usage message for xsubs works out the package name and subroutine name from C<cv>, and then calls C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as: - Perl_croak(aTHX_ "Usage %s::%s(%s)", "ouch" "awk", "eee_yow"); + Perl_croak(aTHX_ "Usage: %s::%s(%s)", "ouch" "awk", "eee_yow"); void croak_xs_usage(const CV *const cv, const char *const params) @@ -4917,6 +6873,16 @@ otherwise use the more efficient C<SvNV>. =for hackers Found in file sv.h +=item SvNV_nomg +X<SvNV_nomg> + +Like C<SvNV> but doesn't process magic. + + NV SvNV_nomg(SV* sv) + +=for hackers +Found in file sv.h + =item SvNV_set X<SvNV_set> @@ -5221,6 +7187,16 @@ Like C<SvPV> but doesn't process magic. =for hackers Found in file sv.h +=item SvPV_nomg_nolen +X<SvPV_nomg_nolen> + +Like C<SvPV_nolen> but doesn't process magic. + + char* SvPV_nomg_nolen(SV* sv) + +=for hackers +Found in file sv.h + =item SvPV_set X<SvPV_set> @@ -5467,13 +7443,26 @@ Found in file sv.h X<SvTRUE> Returns a boolean indicating whether Perl would evaluate the SV as true or -false. See SvOK() for a defined/undefined test. Does not handle 'get' magic. +false. See SvOK() for a defined/undefined test. Handles 'get' magic +unless the scalar is already SvPOK, SvIOK or SvNOK (the public, not the +private flags). bool SvTRUE(SV* sv) =for hackers Found in file sv.h +=item SvTRUE_nomg +X<SvTRUE_nomg> + +Returns a boolean indicating whether Perl would evaluate the SV as true or +false. See SvOK() for a defined/undefined test. Does not handle 'get' magic. + + bool SvTRUE_nomg(SV* sv) + +=for hackers +Found in file sv.h + =item SvTYPE X<SvTYPE> @@ -5612,6 +7601,16 @@ Like C<sv_catpvn> but doesn't process magic. =for hackers Found in file sv.h +=item sv_catpv_nomg +X<sv_catpv_nomg> + +Like C<sv_catpv> but doesn't process magic. + + void sv_catpv_nomg(SV* sv, const char* ptr) + +=for hackers +Found in file sv.h + =item sv_catsv_nomg X<sv_catsv_nomg> @@ -5802,7 +7801,7 @@ SV is set to 1. Note that if C<len> is zero, Perl will create a zero length string. You are responsible for ensuring that the source string is at least C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined. Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>. -If C<SVs_TEMP> is set, then C<sv2mortal()> is called on the result before +If C<SVs_TEMP> is set, then C<sv_2mortal()> is called on the result before returning. If C<SVf_UTF8> is set, C<s> is considered to be in UTF-8 and the C<SVf_UTF8> flag will be set on the new SV. C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as @@ -5863,6 +7862,17 @@ pair and omits the hash parameter. =for hackers Found in file handy.h +=item newSVpv_share +X<newSVpv_share> + +Like C<newSVpvn_share>, but takes a nul-terminated string instead of a +string/length pair. + + SV* newSVpv_share(const char* s, U32 hash) + +=for hackers +Found in file sv.c + =item newSVrv X<newSVrv> @@ -5912,14 +7922,28 @@ Found in file sv.c =item sv_2bool X<sv_2bool> -This function is only called on magical items, and is only used by -sv_true() or its macro equivalent. +This macro is only used by sv_true() or its macro equivalent, and only if +the latter's argument is neither SvPOK, SvIOK nor SvNOK. +It calls sv_2bool_flags with the SV_GMAGIC flag. bool sv_2bool(SV *const sv) =for hackers Found in file sv.c +=item sv_2bool_flags +X<sv_2bool_flags> + +This function is only used by sv_true() and friends, and only if +the latter's argument is neither SvPOK, SvIOK nor SvNOK. If the flags +contain SV_GMAGIC, then it does an mg_get() first. + + + bool sv_2bool_flags(SV *const sv, const I32 flags) + +=for hackers +Found in file sv.c + =item sv_2cv X<sv_2cv> @@ -5970,14 +7994,14 @@ and C<sv_mortalcopy>. =for hackers Found in file sv.c -=item sv_2nv -X<sv_2nv> +=item sv_2nv_flags +X<sv_2nv_flags> Return the num value of an SV, doing any necessary string or integer -conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)> -macros. +conversion. If flags includes SV_GMAGIC, does an mg_get() first. +Normally used via the C<SvNV(sv)> and C<SvNVx(sv)> macros. - NV sv_2nv(SV *const sv) + NV sv_2nv_flags(SV *const sv, const I32 flags) =for hackers Found in file sv.c @@ -6134,6 +8158,52 @@ Like C<sv_catpvn>, but takes a literal string instead of a string/length pair. =for hackers Found in file handy.h +=item sv_catpvs_flags +X<sv_catpvs_flags> + +Like C<sv_catpvn_flags>, but takes a literal string instead of a +string/length pair. + + void sv_catpvs_flags(SV* sv, const char* s, I32 flags) + +=for hackers +Found in file handy.h + +=item sv_catpvs_mg +X<sv_catpvs_mg> + +Like C<sv_catpvn_mg>, but takes a literal string instead of a +string/length pair. + + void sv_catpvs_mg(SV* sv, const char* s) + +=for hackers +Found in file handy.h + +=item sv_catpvs_nomg +X<sv_catpvs_nomg> + +Like C<sv_catpvn_nomg>, but takes a literal string instead of a +string/length pair. + + void sv_catpvs_nomg(SV* sv, const char* s) + +=for hackers +Found in file handy.h + +=item sv_catpv_flags +X<sv_catpv_flags> + +Concatenates the string onto the end of the string which is in the SV. +If the SV has the UTF-8 status set, then the bytes appended should +be valid UTF-8. If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> +on the SVs if appropriate, else not. + + void sv_catpv_flags(SV *dstr, const char *sstr, const I32 flags) + +=for hackers +Found in file sv.c + =item sv_catpv_mg X<sv_catpv_mg> @@ -6195,7 +8265,7 @@ This function should only be called when REFCNT is zero. Most of the time you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>) instead. - void sv_clear(SV *const sv) + void sv_clear(SV *const orig_sv) =for hackers Found in file sv.c @@ -6213,6 +8283,20 @@ coerce its args to strings if necessary. See also C<sv_cmp_locale>. =for hackers Found in file sv.c +=item sv_cmp_flags +X<sv_cmp_flags> + +Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the +string in C<sv1> is less than, equal to, or greater than the string in +C<sv2>. Is UTF-8 and 'use bytes' aware and will coerce its args to strings +if necessary. If the flags include SV_GMAGIC, it handles get magic. See +also C<sv_cmp_locale_flags>. + + I32 sv_cmp_flags(SV *const sv1, SV *const sv2, const U32 flags) + +=for hackers +Found in file sv.c + =item sv_cmp_locale X<sv_cmp_locale> @@ -6225,17 +8309,41 @@ if necessary. See also C<sv_cmp>. =for hackers Found in file sv.c +=item sv_cmp_locale_flags +X<sv_cmp_locale_flags> + +Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and +'use bytes' aware and will coerce its args to strings if necessary. If the +flags contain SV_GMAGIC, it handles get magic. See also C<sv_cmp_flags>. + + I32 sv_cmp_locale_flags(SV *const sv1, SV *const sv2, const U32 flags) + +=for hackers +Found in file sv.c + =item sv_collxfrm X<sv_collxfrm> -Add Collate Transform magic to an SV if it doesn't already have it. +This calls C<sv_collxfrm_flags> with the SV_GMAGIC flag. See +C<sv_collxfrm_flags>. + + char* sv_collxfrm(SV *const sv, STRLEN *const nxp) + +=for hackers +Found in file sv.c + +=item sv_collxfrm_flags +X<sv_collxfrm_flags> + +Add Collate Transform magic to an SV if it doesn't already have it. If the +flags contain SV_GMAGIC, it handles get-magic. Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the scalar data of the variable, but transformed to such a format that a normal memory comparison can be used to compare the data according to the locale settings. - char* sv_collxfrm(SV *const sv, STRLEN *const nxp) + char* sv_collxfrm_flags(SV *const sv, STRLEN *const nxp, I32 const flags) =for hackers Found in file sv.c @@ -6260,13 +8368,24 @@ Found in file sv.c X<sv_dec> Auto-decrement of the value in the SV, doing string to numeric conversion -if necessary. Handles 'get' magic. +if necessary. Handles 'get' magic and operator overloading. void sv_dec(SV *const sv) =for hackers Found in file sv.c +=item sv_dec_nomg +X<sv_dec_nomg> + +Auto-decrement of the value in the SV, doing string to numeric conversion +if necessary. Handles operator overloading. Skips handling 'get' magic. + + void sv_dec_nomg(SV *const sv) + +=for hackers +Found in file sv.c + =item sv_eq X<sv_eq> @@ -6279,6 +8398,18 @@ coerce its args to strings if necessary. =for hackers Found in file sv.c +=item sv_eq_flags +X<sv_eq_flags> + +Returns a boolean indicating whether the strings in the two SVs are +identical. Is UTF-8 and 'use bytes' aware and coerces its args to strings +if necessary. If the flags include SV_GMAGIC, it handles get-magic, too. + + I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags) + +=for hackers +Found in file sv.c + =item sv_force_normal_flags X<sv_force_normal_flags> @@ -6289,7 +8420,7 @@ we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set then a copy-on-write scalar drops its PV buffer (if any) and becomes SvPOK_off rather than making a copy. (Used where this scalar is about to be set to some other value.) In addition, the C<flags> parameter gets passed to -C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function +C<sv_unref_flags()> when unreffing. C<sv_force_normal> calls this function with flags set to 0. void sv_force_normal_flags(SV *const sv, const U32 flags) @@ -6337,13 +8468,24 @@ Found in file sv.c X<sv_inc> Auto-increment of the value in the SV, doing string to numeric conversion -if necessary. Handles 'get' magic. +if necessary. Handles 'get' magic and operator overloading. void sv_inc(SV *const sv) =for hackers Found in file sv.c +=item sv_inc_nomg +X<sv_inc_nomg> + +Auto-increment of the value in the SV, doing string to numeric conversion +if necessary. Handles operator overloading. Skips handling 'get' magic. + + void sv_inc_nomg(SV *const sv) + +=for hackers +Found in file sv.c + =item sv_insert X<sv_insert> @@ -6755,6 +8897,17 @@ Like C<sv_setpvn>, but takes a literal string instead of a string/length pair. =for hackers Found in file handy.h +=item sv_setpvs_mg +X<sv_setpvs_mg> + +Like C<sv_setpvn_mg>, but takes a literal string instead of a +string/length pair. + + void sv_setpvs_mg(SV* sv, const char* s) + +=for hackers +Found in file handy.h + =item sv_setpv_mg X<sv_setpv_mg> @@ -6830,6 +8983,17 @@ Note that C<sv_setref_pv> copies the pointer while this copies the string. =for hackers Found in file sv.c +=item sv_setref_pvs +X<sv_setref_pvs> + +Like C<sv_setref_pvn>, but takes a literal string instead of a +string/length pair. + + SV * sv_setref_pvs(const char* s) + +=for hackers +Found in file handy.h + =item sv_setref_uv X<sv_setref_uv> @@ -6949,6 +9113,16 @@ Removes all magic of type C<type> from an SV. =for hackers Found in file sv.c +=item sv_unmagicext +X<sv_unmagicext> + +Removes all magic of type C<type> with the specified C<vtbl> from an SV. + + int sv_unmagicext(SV *const sv, const int type, MGVTBL *vtbl) + +=for hackers +Found in file sv.c + =item sv_unref_flags X<sv_unref_flags> @@ -7190,6 +9364,23 @@ Found in file sv.c =over 8 +=item bytes_cmp_utf8 +X<bytes_cmp_utf8> + +Compares the sequence of characters (stored as octets) in b, blen with the +sequence of characters (stored as UTF-8) in u, ulen. Returns 0 if they are +equal, -1 or -2 if the first string is less than the second string, +1 or +2 +if the first string is greater than the second string. + +-1 or +1 is returned if the shorter string was identical to the start of the +longer string. -2 or +2 is returned if the was a difference between characters +within the strings. + + int bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u, STRLEN ulen) + +=for hackers +Found in file utf8.c + =item bytes_from_utf8 X<bytes_from_utf8> @@ -7212,9 +9403,10 @@ Found in file utf8.c =item bytes_to_utf8 X<bytes_to_utf8> -Converts a string C<s> of length C<len> from the native encoding into UTF-8. +Converts a string C<s> of length C<len> bytes from the native encoding into +UTF-8. Returns a pointer to the newly-created string, and sets C<len> to -reflect the new length. +reflect the new length in bytes. A NUL character will be written after the end of the string. @@ -7230,31 +9422,45 @@ removed without notice. =for hackers Found in file utf8.c -=item ibcmp_utf8 -X<ibcmp_utf8> +=item foldEQ_utf8 +X<foldEQ_utf8> -Return true if the strings s1 and s2 differ case-insensitively, false -if not (if they are equal case-insensitively). If u1 is true, the -string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true, -the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2 -are false, the respective string is assumed to be in native 8-bit -encoding. +Returns true if the leading portions of the strings s1 and s2 (either or both +of which may be in UTF-8) are the same case-insensitively; false otherwise. +How far into the strings to compare is determined by other input parameters. + +If u1 is true, the string s1 is assumed to be in UTF-8-encoded Unicode; +otherwise it is assumed to be in native 8-bit encoding. Correspondingly for u2 +with respect to s2. + +If the byte length l1 is non-zero, it says how far into s1 to check for fold +equality. In other words, s1+l1 will be used as a goal to reach. The +scan will not be considered to be a match unless the goal is reached, and +scanning won't continue past that goal. Correspondingly for l2 with respect to +s2. + +If pe1 is non-NULL and the pointer it points to is not NULL, that pointer is +considered an end pointer beyond which scanning of s1 will not continue under +any circumstances. This means that if both l1 and pe1 are specified, and pe1 +is less than s1+l1, the match will never be successful because it can never +get as far as its goal (and in fact is asserted against). Correspondingly for +pe2 with respect to s2. -If the pe1 and pe2 are non-NULL, the scanning pointers will be copied -in there (they will point at the beginning of the I<next> character). -If the pointers behind pe1 or pe2 are non-NULL, they are the end -pointers beyond which scanning will not continue under any -circumstances. If the byte lengths l1 and l2 are non-zero, s1+l1 and -s2+l2 will be used as goal end pointers that will also stop the scan, -and which qualify towards defining a successful match: all the scans -that define an explicit length must reach their goal pointers for -a match to succeed). +At least one of s1 and s2 must have a goal (at least one of l1 and l2 must be +non-zero), and if both do, both have to be +reached for a successful match. Also, if the fold of a character is multiple +characters, all of them must be matched (see tr21 reference below for +'folding'). + +Upon a successful match, if pe1 is non-NULL, +it will be set to point to the beginning of the I<next> character of s1 beyond +what was matched. Correspondingly for pe2 and s2. For case-insensitiveness, the "casefolding" of Unicode is used instead of upper/lowercasing both the characters, see http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). - I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2) + I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2) =for hackers Found in file utf8.c @@ -7262,8 +9468,12 @@ Found in file utf8.c =item is_ascii_string X<is_ascii_string> -Returns true if first C<len> bytes of the given string are ASCII (i.e. none -of them even raise the question of UTF-8-ness). +Returns true if the first C<len> bytes of the given string are the same whether +or not the string is encoded in UTF-8 (or UTF-EBCDIC on EBCDIC machines). That +is, if they are invariant. On ASCII-ish machines, only ASCII characters +fit this definition, hence the function's name. + +If C<len> is 0, it will be calculated using C<strlen(s)>. See also is_utf8_string(), is_utf8_string_loclen(), and is_utf8_string_loc(). @@ -7289,9 +9499,10 @@ Found in file utf8.c X<is_utf8_string> Returns true if first C<len> bytes of the given string form a valid -UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does -not mean 'a string that contains code points above 0x7F encoded in UTF-8' -because a valid ASCII string is a valid UTF-8 string. +UTF-8 string, false otherwise. If C<len> is 0, it will be calculated +using C<strlen(s)>. Note that 'a valid UTF-8 string' does not mean 'a +string that contains code points above 0x7F encoded in UTF-8' because a +valid ASCII string is a valid UTF-8 string. See also is_ascii_string(), is_utf8_string_loclen(), and is_utf8_string_loc(). @@ -7415,7 +9626,7 @@ of the result. The "swashp" is a pointer to the swash to use. -Both the special and normal mappings are stored lib/unicore/To/Foo.pl, +Both the special and normal mappings are stored in lib/unicore/To/Foo.pl, and loaded by SWASHNEW, using lib/utf8_heavy.pl. The special (usually, but not always, a multicharacter mapping), is tried first. @@ -7499,14 +9710,12 @@ Found in file utf8.c =item utf8n_to_uvchr X<utf8n_to_uvchr> -flags - -Returns the native character value of the first character in the string +Returns the native character value of the first character in the string C<s> which is assumed to be in UTF-8 encoding; C<retlen> will be set to the length, in bytes, of that character. -Allows length and flags to be passed to low level routine. +length and flags are the same as utf8n_to_uvuni(). UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) @@ -7517,20 +9726,62 @@ Found in file utf8.c X<utf8n_to_uvuni> Bottom level UTF-8 decode routine. -Returns the Unicode code point value of the first character in the string C<s> -which is assumed to be in UTF-8 encoding and no longer than C<curlen>; -C<retlen> will be set to the length, in bytes, of that character. - -If C<s> does not point to a well-formed UTF-8 character, the behaviour -is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY, -it is assumed that the caller will raise a warning, and this function -will silently just set C<retlen> to C<-1> and return zero. If the -C<flags> does not contain UTF8_CHECK_ONLY, warnings about -malformations will be given, C<retlen> will be set to the expected -length of the UTF-8 character in bytes, and zero will be returned. - -The C<flags> can also contain various flags to allow deviations from -the strict UTF-8 encoding (see F<utf8.h>). +Returns the code point value of the first character in the string C<s> +which is assumed to be in UTF-8 (or UTF-EBCDIC) encoding and no longer than +C<curlen> bytes; C<retlen> will be set to the length, in bytes, of that +character. + +The value of C<flags> determines the behavior when C<s> does not point to a +well-formed UTF-8 character. If C<flags> is 0, when a malformation is found, +C<retlen> is set to the expected length of the UTF-8 character in bytes, zero +is returned, and if UTF-8 warnings haven't been lexically disabled, a warning +is raised. + +Various ALLOW flags can be set in C<flags> to allow (and not warn on) +individual types of malformations, such as the sequence being overlong (that +is, when there is a shorter sequence that can express the same code point; +overlong sequences are expressly forbidden in the UTF-8 standard due to +potential security issues). Another malformation example is the first byte of +a character not being a legal first byte. See F<utf8.h> for the list of such +flags. Of course, the value returned by this function under such conditions is +not reliable. + +The UTF8_CHECK_ONLY flag overrides the behavior when a non-allowed (by other +flags) malformation is found. If this flag is set, the routine assumes that +the caller will raise a warning, and this function will silently just set +C<retlen> to C<-1> and return zero. + +Certain code points are considered problematic. These are Unicode surrogates, +Unicode non-characters, and code points above the Unicode maximum of 0x10FFF. +By default these are considered regular code points, but certain situations +warrant special handling for them. if C<flags> contains +UTF8_DISALLOW_ILLEGAL_INTERCHANGE, all three classes are treated as +malformations and handled as such. The flags UTF8_DISALLOW_SURROGATE, +UTF8_DISALLOW_NONCHAR, and UTF8_DISALLOW_SUPER (meaning above the legal Unicode +maximum) can be set to disallow these categories individually. + +The flags UTF8_WARN_ILLEGAL_INTERCHANGE, UTF8_WARN_SURROGATE, +UTF8_WARN_NONCHAR, and UTF8_WARN_SUPER will cause warning messages to be raised +for their respective categories, but otherwise the code points are considered +valid (not malformations). To get a category to both be treated as a +malformation and raise a warning, specify both the WARN and DISALLOW flags. +(But note that warnings are not raised if lexically disabled nor if +UTF8_CHECK_ONLY is also specified.) + +Very large code points (above 0x7FFF_FFFF) are considered more problematic than +the others that are above the Unicode legal maximum. There are several +reasons, one of which is that the original UTF-8 specification never went above +this number (the current 0x10FFF limit was imposed later). The UTF-8 encoding +on ASCII platforms for these large code point begins with a byte containing +0xFE or 0xFF. The UTF8_DISALLOW_FE_FF flag will cause them to be treated as +malformations, while allowing smaller above-Unicode code points. (Of course +UTF8_DISALLOW_SUPER will treat all above-Unicode code points, including these, +as malformations.) Similarly, UTF8_WARN_FE_FF acts just like the other WARN +flags, but applies just to these code points. + +All other code points corresponding to Unicode characters, including private +use and those yet to be assigned, are never considered malformed and never +warn. Most code should use utf8_to_uvchr() rather than call this directly. @@ -7601,7 +9852,7 @@ Found in file utf8.c =item utf8_to_uvchr X<utf8_to_uvchr> -Returns the native character value of the first character in the string C<s> +Returns the native 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. @@ -7634,7 +9885,7 @@ Found in file utf8.c =item uvchr_to_utf8 X<uvchr_to_utf8> -Adds the UTF-8 representation of the Native codepoint C<uv> to the end +Adds the UTF-8 representation of the Native code point C<uv> to the end of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free bytes available. The return value is the pointer to the byte after the end of the new character. In other words, @@ -7653,8 +9904,8 @@ Found in file utf8.c =item uvuni_to_utf8_flags X<uvuni_to_utf8_flags> -Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end -of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free +Adds the UTF-8 representation of the code point C<uv> to the end +of the string C<d>; C<d> should have at least C<UTF8_MAXBYTES+1> free bytes available. The return value is the pointer to the byte after the end of the new character. In other words, @@ -7668,10 +9919,31 @@ or, in most cases, d = uvuni_to_utf8_flags(d, uv, 0); -is the recommended Unicode-aware way of saying +This is the recommended Unicode-aware way of saying *(d++) = uv; +This function will convert to UTF-8 (and not warn) even code points that aren't +legal Unicode or are problematic, unless C<flags> contains one or more of the +following flags. +If C<uv> is a Unicode surrogate code point and UNICODE_WARN_SURROGATE is set, +the function will raise a warning, provided UTF8 warnings are enabled. If instead +UNICODE_DISALLOW_SURROGATE is set, the function will fail and return NULL. +If both flags are set, the function will both warn and return NULL. + +The UNICODE_WARN_NONCHAR and UNICODE_DISALLOW_NONCHAR flags correspondingly +affect how the function handles a Unicode non-character. And, likewise for the +UNICODE_WARN_SUPER and UNICODE_DISALLOW_SUPER flags, and code points that are +above the Unicode maximum of 0x10FFFF. Code points above 0x7FFF_FFFF (which are +even less portable) can be warned and/or disallowed even if other above-Unicode +code points are accepted by the UNICODE_WARN_FE_FF and UNICODE_DISALLOW_FE_FF +flags. + +And finally, the flag UNICODE_WARN_ILLEGAL_INTERCHANGE selects all four of the +above WARN flags; and UNICODE_DISALLOW_ILLEGAL_INTERCHANGE selects all four +DISALLOW flags. + + U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags) =for hackers @@ -7743,8 +10015,9 @@ Found in file XSUB.h =item dUNDERBAR X<dUNDERBAR> -Sets up the C<padoff_du> variable for an XSUB that wishes to use -C<UNDERBAR>. +Sets up any variable needed by the C<UNDERBAR> macro. It used to define +C<padoff_du>, but it is currently a noop. However, it is strongly advised +to still use it for ensuring past and future compatibility. dUNDERBAR; @@ -7857,6 +10130,17 @@ C<xsubpp>. =for hackers Found in file XSUB.h +=item XS_APIVERSION_BOOTCHECK +X<XS_APIVERSION_BOOTCHECK> + +Macro to verify that the perl api version an XS module has been compiled against +matches the api version of the perl interpreter it's being loaded into. + + XS_APIVERSION_BOOTCHECK; + +=for hackers +Found in file XSUB.h + =item XS_VERSION X<XS_VERSION> @@ -7888,19 +10172,132 @@ Found in file XSUB.h =item croak X<croak> -This is the XSUB-writer's interface to Perl's C<die> function. -Normally call this function the same way you call the C C<printf> -function. Calling C<croak> returns control directly to Perl, -sidestepping the normal C order of execution. See C<warn>. +This is an XS interface to Perl's C<die> function. + +Take a sprintf-style format pattern and argument list. These are used to +generate a string message. If the message does not end with a newline, +then it will be extended with some indication of the current location +in the code, as described for L</mess_sv>. + +The error message will be used as an exception, by default +returning control to the nearest enclosing C<eval>, but subject to +modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak> +function never returns normally. + +For historical reasons, if C<pat> is null then the contents of C<ERRSV> +(C<$@>) will be used as an error message or object instead of building an +error message from arguments. If you want to throw a non-string object, +or build an error message in an SV yourself, it is preferable to use +the L</croak_sv> function, which does not involve clobbering C<ERRSV>. + + void croak(const char *pat, ...) + +=for hackers +Found in file util.c + +=item croak_no_modify +X<croak_no_modify> + +Exactly equivalent to C<Perl_croak(aTHX_ "%s", PL_no_modify)>, but generates +terser object code than using C<Perl_croak>. Less code used on exception code +paths reduces CPU cache pressure. + + void croak_no_modify() + +=for hackers +Found in file util.c + +=item croak_sv +X<croak_sv> + +This is an XS interface to Perl's C<die> function. + +C<baseex> is the error message or object. If it is a reference, it +will be used as-is. Otherwise it is used as a string, and if it does +not end with a newline then it will be extended with some indication of +the current location in the code, as described for L</mess_sv>. + +The error message or object will be used as an exception, by default +returning control to the nearest enclosing C<eval>, but subject to +modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak_sv> +function never returns normally. + +To die with a simple string message, the L</croak> function may be +more convenient. + + void croak_sv(SV *baseex) -If you want to throw an exception object, assign the object to -C<$@> and then pass C<NULL> to croak(): +=for hackers +Found in file util.c + +=item die +X<die> - errsv = get_sv("@", GV_ADD); - sv_setsv(errsv, exception_object); - croak(NULL); +Behaves the same as L</croak>, except for the return type. +It should be used only where the C<OP *> return type is required. +The function never actually returns. - void croak(const char* pat, ...) + OP * die(const char *pat, ...) + +=for hackers +Found in file util.c + +=item die_sv +X<die_sv> + +Behaves the same as L</croak_sv>, except for the return type. +It should be used only where the C<OP *> return type is required. +The function never actually returns. + + OP * die_sv(SV *baseex) + +=for hackers +Found in file util.c + +=item vcroak +X<vcroak> + +This is an XS interface to Perl's C<die> function. + +C<pat> and C<args> are a sprintf-style format pattern and encapsulated +argument list. These are used to generate a string message. If the +message does not end with a newline, then it will be extended with +some indication of the current location in the code, as described for +L</mess_sv>. + +The error message will be used as an exception, by default +returning control to the nearest enclosing C<eval>, but subject to +modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak> +function never returns normally. + +For historical reasons, if C<pat> is null then the contents of C<ERRSV> +(C<$@>) will be used as an error message or object instead of building an +error message from arguments. If you want to throw a non-string object, +or build an error message in an SV yourself, it is preferable to use +the L</croak_sv> function, which does not involve clobbering C<ERRSV>. + + void vcroak(const char *pat, va_list *args) + +=for hackers +Found in file util.c + +=item vwarn +X<vwarn> + +This is an XS interface to Perl's C<warn> function. + +C<pat> and C<args> are a sprintf-style format pattern and encapsulated +argument list. These are used to generate a string message. If the +message does not end with a newline, then it will be extended with +some indication of the current location in the code, as described for +L</mess_sv>. + +The error message or object will by default be written to standard error, +but this is subject to modification by a C<$SIG{__WARN__}> handler. + +Unlike with L</vcroak>, C<pat> is not permitted to be null. + + void vwarn(const char *pat, va_list *args) =for hackers Found in file util.c @@ -7908,10 +10305,40 @@ Found in file util.c =item warn X<warn> -This is the XSUB-writer's interface to Perl's C<warn> function. Call this -function the same way you call the C C<printf> function. See C<croak>. +This is an XS interface to Perl's C<warn> function. + +Take a sprintf-style format pattern and argument list. These are used to +generate a string message. If the message does not end with a newline, +then it will be extended with some indication of the current location +in the code, as described for L</mess_sv>. + +The error message or object will by default be written to standard error, +but this is subject to modification by a C<$SIG{__WARN__}> handler. - void warn(const char* pat, ...) +Unlike with L</croak>, C<pat> is not permitted to be null. + + void warn(const char *pat, ...) + +=for hackers +Found in file util.c + +=item warn_sv +X<warn_sv> + +This is an XS interface to Perl's C<warn> function. + +C<baseex> is the error message or object. If it is a reference, it +will be used as-is. Otherwise it is used as a string, and if it does +not end with a newline then it will be extended with some indication of +the current location in the code, as described for L</mess_sv>. + +The error message or object will by default be written to standard error, +but this is subject to modification by a C<$SIG{__WARN__}> handler. + +To warn with a simple string message, the L</warn> function may be +more convenient. + + void warn_sv(SV *baseex) =for hackers Found in file util.c @@ -7921,7 +10348,13 @@ Found in file util.c =head1 Undocumented functions -These functions are currently undocumented: +The following functions have been flagged as part of the public API, +but are currently undocumented. Use them at your own risk, as the +interfaces are subject to change. + +If you use one of them, you may wish to consider creating and submitting +documentation for it. If your patch is accepted, this will indicate that +the interface is stable (unless it is explicitly marked otherwise). =over @@ -8006,9 +10439,18 @@ X<Slab_Alloc> =item Slab_Free X<Slab_Free> +=item _to_uni_fold_flags +X<_to_uni_fold_flags> + +=item _to_utf8_fold_flags +X<_to_utf8_fold_flags> + =item amagic_call X<amagic_call> +=item amagic_deref_call +X<amagic_deref_call> + =item any_dup X<any_dup> @@ -8063,18 +10505,18 @@ X<ckwarn> =item ckwarn_d X<ckwarn_d> +=item clone_params_del +X<clone_params_del> + +=item clone_params_new +X<clone_params_new> + =item croak_nocontext X<croak_nocontext> =item csighandler X<csighandler> -=item custom_op_desc -X<custom_op_desc> - -=item custom_op_name -X<custom_op_name> - =item cx_dump X<cx_dump> @@ -8108,9 +10550,6 @@ X<delimcpy> =item despatch_signals X<despatch_signals> -=item die -X<die> - =item die_nocontext X<die_nocontext> @@ -8219,9 +10658,18 @@ X<filter_del> =item filter_read X<filter_read> +=item find_rundefsv +X<find_rundefsv> + =item find_rundefsvoffset X<find_rundefsvoffset> +=item foldEQ_latin1 +X<foldEQ_latin1> + +=item foldEQ_utf8_flags +X<foldEQ_utf8_flags> + =item form_nocontext X<form_nocontext> @@ -8381,12 +10829,6 @@ X<hv_riter_set> =item hv_store_flags X<hv_store_flags> -=item ibcmp -X<ibcmp> - -=item ibcmp_locale -X<ibcmp_locale> - =item init_global_struct X<init_global_struct> @@ -8540,6 +10982,12 @@ X<is_utf8_upper> =item is_utf8_xdigit X<is_utf8_xdigit> +=item is_utf8_xidcont +X<is_utf8_xidcont> + +=item is_utf8_xidfirst +X<is_utf8_xidfirst> + =item leave_scope X<leave_scope> @@ -8555,9 +11003,6 @@ X<malloc> =item markstack_grow X<markstack_grow> -=item mess -X<mess> - =item mess_nocontext X<mess_nocontext> @@ -8684,36 +11129,18 @@ X<newANONLIST> =item newANONSUB X<newANONSUB> -=item newASSIGNOP -X<newASSIGNOP> - =item newATTRSUB X<newATTRSUB> =item newAVREF X<newAVREF> -=item newBINOP -X<newBINOP> - -=item newCONDOP -X<newCONDOP> - =item newCVREF X<newCVREF> =item newFORM X<newFORM> -=item newFOROP -X<newFOROP> - -=item newGIVENOP -X<newGIVENOP> - -=item newGVOP -X<newGVOP> - =item newGVREF X<newGVREF> @@ -8729,72 +11156,24 @@ X<newHVhv> =item newIO X<newIO> -=item newLISTOP -X<newLISTOP> - -=item newLOGOP -X<newLOGOP> - -=item newLOOPEX -X<newLOOPEX> - -=item newLOOPOP -X<newLOOPOP> - =item newMYSUB X<newMYSUB> -=item newNULLLIST -X<newNULLLIST> - -=item newOP -X<newOP> - -=item newPADOP -X<newPADOP> - -=item newPMOP -X<newPMOP> - =item newPROG X<newPROG> -=item newPVOP -X<newPVOP> - -=item newRANGE -X<newRANGE> - =item newRV X<newRV> -=item newSLICEOP -X<newSLICEOP> - -=item newSTATEOP -X<newSTATEOP> - =item newSUB X<newSUB> -=item newSVOP -X<newSVOP> - =item newSVREF X<newSVREF> =item newSVpvf_nocontext X<newSVpvf_nocontext> -=item newUNOP -X<newUNOP> - -=item newWHENOP -X<newWHENOP> - -=item newWHILEOP -X<newWHILEOP> - =item newXS_flags X<newXS_flags> @@ -9023,6 +11402,9 @@ X<save_destructor> =item save_destructor_x X<save_destructor_x> +=item save_freeop +X<save_freeop> + =item save_freepv X<save_freepv> @@ -9050,6 +11432,9 @@ X<save_helem> =item save_helem_flags X<save_helem_flags> +=item save_hints +X<save_hints> + =item save_hptr X<save_hptr> @@ -9074,15 +11459,24 @@ X<save_mortalizesv> =item save_nogv X<save_nogv> +=item save_op +X<save_op> + =item save_padsv_and_mortalize X<save_padsv_and_mortalize> =item save_pptr X<save_pptr> +=item save_pushi32ptr +X<save_pushi32ptr> + =item save_pushptr X<save_pushptr> +=item save_pushptrptr +X<save_pushptrptr> + =item save_re_context X<save_re_context> @@ -9179,6 +11573,9 @@ X<sv_dump> =item sv_dup X<sv_dup> +=item sv_dup_inc +X<sv_dup_inc> + =item sv_peek X<sv_peek> @@ -9266,9 +11663,6 @@ X<uvchr_to_utf8_flags> =item uvuni_to_utf8 X<uvuni_to_utf8> -=item vcroak -X<vcroak> - =item vdeb X<vdeb> @@ -9278,15 +11672,9 @@ X<vform> =item vload_module X<vload_module> -=item vmess -X<vmess> - =item vnewSVpvf X<vnewSVpvf> -=item vwarn -X<vwarn> - =item vwarner X<vwarner> diff --git a/Master/tlpkg/tlperl/lib/pods/perlapollo.pod b/Master/tlpkg/tlperl/lib/pods/perlapollo.pod deleted file mode 100644 index cc12e6a5cd6..00000000000 --- a/Master/tlpkg/tlperl/lib/pods/perlapollo.pod +++ /dev/null @@ -1,23 +0,0 @@ -If you read this file _as_is_, just ignore the funny characters you see. -It is written in the POD format (see pod/perlpod.pod) which is specially -designed to be readable as is. - -=head1 NAME - -README.apollo - Perl version 5 on Apollo DomainOS - -=head1 DESCRIPTION - -The following tests are known to fail as of Perl 5.005_03: - -comp/decl..........FAILED at test 0 -op/write...........FAILED at test 0 -lib/filefind.......FAILED at test 2 -lib/io_udp.........FAILED at test 2 -lib/findbin........stat(/ressel/ABT/USER/vta/jk/proj.local/perl/perl5.005_03-MAINT_TRIAL_5/t/lib/): No such file or directory at ../lib/FindBin.pm line 162 -stat(/ressel/ABT/USER/vta/jk/proj.local/perl/perl5.005_03-MAINT_TRIAL_5/t/lib/): No such file or directory at ../lib/FindBin.pm line 163 -FAILED at test 1 - -=head1 AUTHOR - -Johann Klasek <jk@auto.tuwien.ac.at> diff --git a/Master/tlpkg/tlperl/lib/pods/perlbook.pod b/Master/tlpkg/tlperl/lib/pods/perlbook.pod index b48379f5644..f780c9bb6ac 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlbook.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlbook.pod @@ -1,17 +1,295 @@ =head1 NAME -perlbook - Perl book information +perlbook - Books about and related to Perl =head1 DESCRIPTION -The Camel Book, officially known as I<Programming Perl, Third Edition>, -by Larry Wall et al, is the definitive reference work covering nearly -all of Perl. You can order it and other Perl books from O'Reilly & -Associates, 1-800-998-9938. Local/overseas is +1 707 829 0515. If you -can locate an O'Reilly order form, you can also fax to +1 707 829 0104. -If you're web-connected, you can even mosey on over to -L<http://www.oreilly.com/> for an online order form. - -Other Perl books from various publishers and authors -can be found listed in L<perlfaq2> or on the web at -L<http://books.perl.org/>. +There are many books on Perl and Perl-related. A few of these are +good, some are OK, but many aren't worth your money. There is a list +of these books, some with extensive reviews, at http://books.perl.org/ +. We list some of the books here, and while listing a book implies our +endorsement, don't think that not including a book means anything. + +Most of these books are available online through Safari Books Online +( http://safaribooksonline.com/ ). + +=head2 The most popular books + +The major reference book on Perl, written by the creator of Perl, is +I<Programming Perl>: + +=over 4 + +=item I<Programming Perl> (the "Camel Book"): + + by Larry Wall, Tom Christiansen, and Jon Orwant + ISBN 978-0-596-00027-1 [3rd edition July 2000] + http://oreilly.com/catalog/9780596000271/ + +=back + +The Ram is a cookbook with hundreds of examples of using Perl to +accomplish specific tasks: + +=over 4 + +=item I<The Perl Cookbook> (the "Ram Book"): + + by Tom Christiansen and Nathan Torkington, + with Foreword by Larry Wall + ISBN 978-0-596-00313-5 [2nd Edition August 2003] + http://oreilly.com/catalog/9780596003135/ + +=back + +If you want to learn the basics of Perl, you might start with the +Llama book, which assumes that you already know a little about +programming: + +=over 4 + +=item I<Learning Perl> (the "Llama Book") + + by Randal L. Schwartz, Tom Phoenix, and brian d foy + ISBN 978-0-596-52011-3 [5th edition June 2008] + http://oreilly.com/catalog/9780596520113 + +=back + +The tutorial started in the Llama continues in the Alpaca, which +introduces the intermediate features of references, data structures, +object-oriented programming, and modules: + +=over 4 + +=item I<Intermediate Perl> (the "Alpaca Book") + + by Randal L. Schwartz and brian d foy, with Tom Phoenix + foreword by Damian Conway + ISBN 978-0-596-00478-1 [1st edition March 2006] + http://oreilly.com/catalog/9780596004781/ + +=back + +=head2 References + +You might want to keep these desktop references close by your keyboard: + +=over 4 + +=item I<Perl 5 Pocket Reference> + + by Johan Vromans + ISBN 978-0-596-00374-6 [4th edition July 2002] + http://oreilly.com/catalog/9780596003746/ + +=item I<Perl Debugger Pocket Reference> + + by Richard Foley + ISBN 978-0-596-00503-0 [1st edition January 2004] + http://oreilly.com/catalog/9780596005030/ + +=item I<Regular Expression Pocket Reference> + + by Tony Stubblebine + ISBN 978-0-596-51427-3 [July 2007] + http://oreilly.com/catalog/9780596514273/ + +=back + +=head2 Tutorials + +=over 4 + +=item I<Beginning Perl> + + by James Lee + ISBN 1-59059-391-X [3rd edition April 2010] + http://www.apress.com/book/view/1430227931 + +=item I<Learning Perl> + + by Randal L. Schwartz, Tom Phoenix, and brian d foy + ISBN 978-0-596-52010-6 [5th edition June 2008] + http://oreilly.com/catalog/9780596520106 + +=item I<Intermediate Perl> (the "Alpaca Book") + + by Randal L. Schwartz and brian d foy, with Tom Phoenix + foreword by Damian Conway + ISBN 0-596-10206-2 [1st edition March 2006] + http://oreilly.com/catalog/9780596102067 + +=item I<Mastering Perl> + + by brian d foy + ISBN 978-0-596-10206-7 [1st edition July 2007] + http://www.oreilly.com/catalog/9780596527242 + +=item I<Effective Perl Programming> + + by Joseph N. Hall, Joshua A. McAdams, brian d foy + ISBN 0-321-49694-9 [2nd edition 2010] + http://www.effectiveperlprogramming.com/ + +=back + +=head2 Task-Oriented + +=over 4 + +=item I<Writing Perl Modules for CPAN> + + by Sam Tregar + ISBN 1-59059-018-X [1st edition August 2002] + http://www.apress.com/book/view/159059018X + +=item I<The Perl Cookbook> + + by Tom Christiansen and Nathan Torkington + with foreword by Larry Wall + ISBN 1-56592-243-3 [2nd edition August 2003] + http://oreilly.com/catalog/9780596003135 + + +=item I<Automating System Administration with Perl> + + by David N. Blank-Edelman + ISBN 978-0-596-00639-6 [2nd edition May 2009] + http://oreilly.com/catalog/9780596006396 + +=item I<Real World SQL Server Administration with Perl> + + by Linchi Shea + ISBN 1-59059-097-X [1st edition July 2003] + http://www.apress.com/book/view/159059097X + +=back + +=head2 Special Topics + +=over 4 + +=item I<Regular Expressions Cookbook> + + by Jan Goyvaerts and Steven Levithan + ISBN 978-0-596-52069-4 [May 2009] + http://oreilly.com/catalog/9780596520694 + +=item I<Programming the Perl DBI> + + by Tim Bunce and Alligator Descartes + ISBN 978-1-56592-699-8 [February 2000] + http://oreilly.com/catalog/9781565926998 + +=item I<Perl Best Practices> + + by Damian Conway + ISBN: 978-0-596-00173-5 [1st edition July 2005] + http://oreilly.com/catalog/9780596001735 + +=item I<Higher-Order Perl> + + by Mark-Jason Dominus + ISBN: 1-55860-701-3 [1st edition March 2005] + http://hop.perl.plover.com/ + +=item I<Mastering Regular Expressions> + + by Jeffrey E. F. Friedl + ISBN 978-0-596-52812-6 [3rd edition August 2006] + http://oreilly.com/catalog/9780596528126 + +=item I<Network Programming with Perl> + + by Lincoln Stein + ISBN 0-201-61571-1 [1st edition 2001] + http://www.pearsonhighered.com/educator/product/Network-Programming-with-Perl/9780201615715.page + +=item I<Perl Template Toolkit> + + by Darren Chamberlain, Dave Cross, and Andy Wardley + ISBN 978-0-596-00476-7 [December 2003] + http://oreilly.com/catalog/9780596004767 + +=item I<Object Oriented Perl> + + by Damian Conway + with foreword by Randal L. Schwartz + ISBN 1-884777-79-1 [1st edition August 1999] + http://www.manning.com/conway/ + +=item I<Data Munging with Perl> + + by Dave Cross + ISBN 1-930110-00-6 [1st edition 2001] + http://www.manning.com/cross + +=item I<Mastering Perl/Tk> + + by Steve Lidie and Nancy Walsh + ISBN 978-1-56592-716-2 [1st edition January 2002] + http://oreilly.com/catalog/9781565927162 + +=item I<Extending and Embedding Perl> + + by Tim Jenness and Simon Cozens + ISBN 1-930110-82-0 [1st edition August 2002] + http://www.manning.com/jenness + +=item I<Pro Perl Debugging> + + by Richard Foley with Andy Lester + ISBN 1-59059-454-1 [1st edition July 2005] + http://www.apress.com/book/view/1590594541 + +=back + +=head2 Free (as in beer) books + +Some of these books are available as free downloads. + +I<Higher-Order Perl>: http://hop.perl.plover.com/ + +I<Writing Perl Modules for CPAN>: http://www.apress.com/resource/freeebook/9781590590188 + +=head2 Other interesting, non-Perl books + +You might notice several familiar Perl concepts in this collection of +ACM columns from Jon Bentley. The similarity to the title of the major +Perl book (which came later) is not completely accidental: + +=over 4 + +=item I<Programming Pearls> + + by Jon Bentley + ISBN 978-0-201-65788-3 [2 edition, October 1999] + +=item I<More Programming Pearls> + + by Jon Bentley + ISBN 0-201-11889-0 [January 1988] + +=back + +=head2 A note on freshness + +Each version of Perl comes with the documentation that was current at +the time of release. This poses a problem for content such as book +lists. There are probably very nice books published after this list +was included in your Perl release, and you can check the latest +released version at http://perldoc.perl.org/perlbook.html . + +Some of the books we've listed appear almost ancient in internet +scale, but we've included those books because they still describe the +current way of doing things. Not everything in Perl changes every day. +Many of the beginner-level books, too, go over basic features and +techniques that are still valid today. In general though, we try to +limit this list to books published in the past five years. + +=head2 Get your book listed + +If your Perl book isn't listed and you think it should be, let us know. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlboot.pod b/Master/tlpkg/tlperl/lib/pods/perlboot.pod index a6b256a0fcc..5aa61795759 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlboot.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlboot.pod @@ -253,7 +253,7 @@ The easiest is to just spell the package name out: @Cow::ISA = qw(Animal); -Or declare it as package global variable: +Or declare it as a package global variable: package Cow; our @ISA = qw(Animal); diff --git a/Master/tlpkg/tlperl/lib/pods/perlbot.pod b/Master/tlpkg/tlperl/lib/pods/perlbot.pod index 91723b70d78..305a6951b7f 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlbot.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlbot.pod @@ -1,6 +1,6 @@ =head1 NAME -perlbot - Bag'o Object Tricks (the BOT) +perlbot - Bag o' Object Tricks (the BOT) =head1 DESCRIPTION diff --git a/Master/tlpkg/tlperl/lib/pods/perlbs2000.pod b/Master/tlpkg/tlperl/lib/pods/perlbs2000.pod index a7746c64e2b..b13d9840d27 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlbs2000.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlbs2000.pod @@ -206,7 +206,7 @@ Perl, that it should use the native IO layer: Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC partitions. See the documentation of PerlIO (without C<Encode::>!) -for further posibilities. +for further possibilities. =head1 AUTHORS diff --git a/Master/tlpkg/tlperl/lib/pods/perlcall.pod b/Master/tlpkg/tlperl/lib/pods/perlcall.pod index 359e097a18d..df03ed6f200 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlcall.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlcall.pod @@ -25,10 +25,10 @@ function that will be called whenever something nasty occurs. What we would like is to be able to specify a Perl subroutine that will be called instead. -=item * An Event Driven Program +=item * An Event-Driven Program The classic example of where callbacks are used is when writing an -event driven program like for an X windows application. In this case +event driven program, such as for an X windows application. In this case you register functions to be called whenever specific events occur, e.g., a mouse button is pressed, the cursor moves into a window or a menu item is selected. @@ -42,8 +42,8 @@ embedding Perl. For details on embedding Perl in C refer to L<perlembed>. Before you launch yourself head first into the rest of this document, -it would be a good idea to have read the following two documents - -L<perlxs> and L<perlguts>. +it would be a good idea to have read the following two documents--L<perlxs> +and L<perlguts>. =head1 THE CALL_ FUNCTIONS @@ -74,7 +74,7 @@ Each of the functions will now be discussed in turn. =item call_sv -I<call_sv> takes two parameters, the first, C<sv>, is an SV*. +I<call_sv> takes two parameters. The first, C<sv>, is an SV*. This allows you to specify the Perl subroutine to be called either as a C string (which has first been converted to an SV) or a reference to a subroutine. The section, I<Using call_sv>, shows how you can make @@ -103,7 +103,7 @@ of using I<call_method>. I<call_argv> calls the Perl subroutine specified by the C string stored in the C<subname> parameter. It also takes the usual C<flags> -parameter. The final parameter, C<argv>, consists of a NULL terminated +parameter. The final parameter, C<argv>, consists of a NULL-terminated list of C strings to be passed as parameters to the Perl subroutine. See I<Using call_argv>. @@ -121,10 +121,9 @@ been warned. =head1 FLAG VALUES -The C<flags> parameter in all the I<call_*> functions is a bit mask -which can consist of any combination of the symbols defined below, -OR'ed together. - +The C<flags> parameter in all the I<call_*> functions is one of G_VOID, +G_SCALAR, or G_ARRAY, which indicate the call context, OR'ed together +with a bit mask of any combination of the other G_* symbols defined below. =head2 G_VOID @@ -147,7 +146,7 @@ It ensures that nothing is actually returned from the subroutine. =back The value returned by the I<call_*> function indicates how many -items have been returned by the Perl subroutine - in this case it will +items have been returned by the Perl subroutine--in this case it will be 0. @@ -249,7 +248,7 @@ the effect of not creating the C<@_> array for the Perl subroutine. Although the functionality provided by this flag may seem straightforward, it should be used only if there is a good reason to do -so. The reason for being cautious is that even if you have specified +so. The reason for being cautious is that, even if you have specified the G_NOARGS flag, it is still possible for the Perl subroutine that has been called to think that you have passed it parameters. @@ -321,33 +320,34 @@ See I<Using G_EVAL> for details on using G_EVAL. =head2 G_KEEPERR -You may have noticed that using the G_EVAL flag described above will -B<always> clear the C<$@> variable and set it to a string describing -the error iff there was an error in the called code. This unqualified -resetting of C<$@> can be problematic in the reliable identification of -errors using the C<eval {}> mechanism, because the possibility exists -that perl will call other code (end of block processing code, for -example) between the time the error causes C<$@> to be set within -C<eval {}>, and the subsequent statement which checks for the value of -C<$@> gets executed in the user's script. - -This scenario will mostly be applicable to code that is meant to be -called from within destructors, asynchronous callbacks, signal -handlers, C<__DIE__> or C<__WARN__> hooks, and C<tie> functions. In -such situations, you will not want to clear C<$@> at all, but simply to -append any new errors to any existing value of C<$@>. +Using the G_EVAL flag described above will always set C<$@>: clearing +it if there was no error, and setting it to describe the error if there +was an error in the called code. This is what you want if your intention +is to handle possible errors, but sometimes you just want to trap errors +and stop them interfering with the rest of the program. + +This scenario will mostly be applicable to code that is meant to be called +from within destructors, asynchronous callbacks, and signal handlers. +In such situations, where the code being called has little relation to the +surrounding dynamic context, the main program needs to be insulated from +errors in the called code, even if they can't be handled intelligently. +It may also be useful to do this with code for C<__DIE__> or C<__WARN__> +hooks, and C<tie> functions. The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in -I<call_*> functions that are used to implement such code. This flag -has no effect when G_EVAL is not used. +I<call_*> functions that are used to implement such code, or with +C<eval_sv>. This flag has no effect on the C<call_*> functions when +G_EVAL is not used. -When G_KEEPERR is used, any errors in the called code will be prefixed -with the string "\t(in cleanup)", and appended to the current value -of C<$@>. an error will not be appended if that same error string is -already at the end of C<$@>. +When G_KEEPERR is used, any error in the called code will terminate the +call as usual, and the error will not propagate beyond the call (as usual +for G_EVAL), but it will not go into C<$@>. Instead the error will be +converted into a warning, prefixed with the string "\t(in cleanup)". +This can be disabled using C<no warnings 'misc'>. If there is no error, +C<$@> will not be cleared. -In addition, a warning is generated using the appended string. This can be -disabled using C<no warnings 'misc'>. +Note that the G_KEEPERR flag does not propagate into inner evals; these +may still set C<$@>. The G_KEEPERR flag was introduced in Perl version 5.002. @@ -360,7 +360,7 @@ As mentioned above, you can determine the context of the currently executing subroutine in Perl with I<wantarray>. The equivalent test can be made in C by using the C<GIMME_V> macro, which returns C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if -in a scalar context, or C<G_VOID> if in a void context (i.e. the +in a scalar context, or C<G_VOID> if in a void context (i.e., the return value will not be used). An older version of this macro is called C<GIMME>; in a void context it returns C<G_SCALAR> instead of C<G_VOID>. An example of using the C<GIMME_V> macro is shown in @@ -368,7 +368,7 @@ section I<Using GIMME_V>. =head1 EXAMPLES -Enough of the definition talk, let's have a few examples. +Enough of the definition talk! Let's have a few examples. Perl provides many macros to assist in accessing the Perl stack. Wherever possible, these macros should always be used when interfacing @@ -382,7 +382,7 @@ possible, if the choice is between using I<call_pv> and I<call_sv>, you should always try to use I<call_sv>. See I<Using call_sv> for details. -=head2 No Parameters, Nothing returned +=head2 No Parameters, Nothing Returned This first trivial example will call a Perl subroutine, I<PrintUID>, to print out the UID of the process. @@ -403,9 +403,9 @@ and here is a C function to call it call_pv("PrintUID", G_DISCARD|G_NOARGS); } -Simple, eh. +Simple, eh? -A few points to note about this example. +A few points to note about this example: =over 5 @@ -446,7 +446,7 @@ call a Perl subroutine, C<LeftString>, which will take 2 parameters--a string ($s) and an integer ($n). The subroutine will simply print the first $n characters of the string. -So the Perl subroutine would look like this +So the Perl subroutine would look like this: sub LeftString { @@ -454,7 +454,7 @@ So the Perl subroutine would look like this print substr($s, 0, $n), "\n"; } -The C function required to call I<LeftString> would look like this. +The C function required to call I<LeftString> would look like this: static void call_LeftString(a, b) @@ -513,13 +513,13 @@ subroutine, it knows how big to make it. The C<PUSHMARK> macro tells Perl to make a mental note of the current stack pointer. Even if you aren't passing any parameters (like the -example shown in the section I<No Parameters, Nothing returned>) you +example shown in the section I<No Parameters, Nothing Returned>) you must still call the C<PUSHMARK> macro before you can call any of the I<call_*> functions--Perl still needs to know that there are no parameters. The C<PUTBACK> macro sets the global copy of the stack pointer to be -the same as our local copy. If we didn't do this I<call_pv> +the same as our local copy. If we didn't do this, I<call_pv> wouldn't know where the two parameters we pushed were--remember that up to now all the stack pointer manipulation we have done is with our local copy, I<not> the global copy. @@ -557,10 +557,10 @@ the Perl subroutine (see next example), plus it will also dump the mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the beginning of the code makes sure that no other mortals are destroyed. -Think of these macros as working a bit like using C<{> and C<}> in Perl +Think of these macros as working a bit like C<{> and C<}> in Perl to limit the scope of local variables. -See the section I<Using Perl to dispose of temporaries> for details of +See the section I<Using Perl to Dispose of Temporaries> for details of an alternative to using these macros. =item 6. @@ -625,7 +625,7 @@ Points to note this time are =item 1. -The only flag specified this time was G_SCALAR. That means the C<@_> +The only flag specified this time was G_SCALAR. That means that the C<@_> array will be created and that the value returned by I<Adder> will still exist after the call to I<call_pv>. @@ -633,7 +633,7 @@ still exist after the call to I<call_pv>. The purpose of the macro C<SPAGAIN> is to refresh the local copy of the stack pointer. This is necessary because it is possible that the memory -allocated to the Perl stack has been reallocated whilst in the +allocated to the Perl stack has been reallocated during the I<call_pv> call. If you are making use of the Perl stack pointer in your code you must @@ -678,7 +678,7 @@ stack pointer to be the same as our local copy. =back -=head2 Returning a list of values +=head2 Returning a List of Values Now, let's extend the previous example to return both the sum of the parameters and the difference. @@ -750,7 +750,7 @@ order. =back -=head2 Returning a list in a scalar context +=head2 Returning a List in a Scalar Context Say the Perl subroutine in the previous section was called in a scalar context, like this @@ -799,14 +799,14 @@ then the output will be Value 1 = 3 In this case the main point to note is that only the last item in the -list is returned from the subroutine, I<AddSubtract> actually made it back to +list is returned from the subroutine. I<AddSubtract> actually made it back to I<call_AddSubScalar>. -=head2 Returning Data from Perl via the parameter list +=head2 Returning Data from Perl via the Parameter List -It is also possible to return values directly via the parameter list - -whether it is actually desirable to do it is another matter entirely. +It is also possible to return values directly via the parameter +list--whether it is actually desirable to do it is another matter entirely. The Perl subroutine, I<Inc>, below takes 2 parameters and increments each directly. @@ -965,7 +965,7 @@ C<SvTRUE(ERRSV)> is true. This is necessary because whenever a I<call_*> function invoked with G_EVAL|G_SCALAR returns an error, the top of the stack holds the value I<undef>. Because we want the program to continue after detecting this error, it is essential that -the stack is tidied up by removing the I<undef>. +the stack be tidied up by removing the I<undef>. =back @@ -986,12 +986,15 @@ version of the call_Subtract example above inside a destructor: sub foo { die "foo dies"; } package main; - eval { Foo->new->foo }; + { + my $foo = Foo->new; + eval { $foo->foo }; + } print "Saw: $@" if $@; # should be, but isn't This example will fail to recognize that an error occurred inside the C<eval {}>. Here's why: the call_Subtract code got executed while perl -was cleaning up temporaries when exiting the eval block, and because +was cleaning up temporaries when exiting the outer braced block, and because call_Subtract is implemented with I<call_pv> using the G_EVAL flag, it promptly reset C<$@>. This results in the failure of the outermost test for C<$@>, and thereby the failure of the error trap. @@ -1044,7 +1047,7 @@ I<call_sv> instead of I<call_pv>. PUSHMARK(SP); call_sv(name, G_DISCARD|G_NOARGS); -Because we are using an SV to call I<fred> the following can all be used +Because we are using an SV to call I<fred> the following can all be used: CallSubSV("fred"); CallSubSV(\&fred); @@ -1055,10 +1058,10 @@ Because we are using an SV to call I<fred> the following can all be used As you can see, I<call_sv> gives you much greater flexibility in how you can specify the Perl subroutine. -You should note that if it is necessary to store the SV (C<name> in the +You should note that, if it is necessary to store the SV (C<name> in the example above) which corresponds to the Perl subroutine so that it can be used later in the program, it not enough just to store a copy of the -pointer to the SV. Say the code above had been like this +pointer to the SV. Say the code above had been like this: static SV * rememberSub; @@ -1074,10 +1077,10 @@ pointer to the SV. Say the code above had been like this PUSHMARK(SP); call_sv(rememberSub, G_DISCARD|G_NOARGS); -The reason this is wrong is that by the time you come to use the +The reason this is wrong is that, by the time you come to use the pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer to the Perl subroutine that was recorded in C<SaveSub1>. This is -particularly true for these cases +particularly true for these cases: SaveSub1(\&fred); CallSavedSub1(); @@ -1085,7 +1088,7 @@ particularly true for these cases SaveSub1( sub { print "Hello there\n" } ); CallSavedSub1(); -By the time each of the C<SaveSub1> statements above have been executed, +By the time each of the C<SaveSub1> statements above has been executed, the SV*s which corresponded to the parameters will no longer exist. Expect an error message from Perl of the form @@ -1116,19 +1119,19 @@ code which is referenced by the SV* C<rememberSub>. In this case though, it now refers to the integer C<47>, so expect Perl to complain loudly. -A similar but more subtle problem is illustrated with this code +A similar but more subtle problem is illustrated with this code: $ref = \&fred; SaveSub1($ref); $ref = \&joe; CallSavedSub1(); -This time whenever C<CallSavedSub1> get called it will execute the Perl +This time whenever C<CallSavedSub1> gets called it will execute the Perl subroutine C<joe> (assuming it exists) rather than C<fred> as was originally requested in the call to C<SaveSub1>. To get around these problems it is necessary to take a full copy of the -SV. The code below shows C<SaveSub2> modified to do that +SV. The code below shows C<SaveSub2> modified to do that. static SV * keepSub = (SV*)NULL; @@ -1153,8 +1156,8 @@ SV. The code below shows C<SaveSub2> modified to do that To avoid creating a new SV every time C<SaveSub2> is called, the function first checks to see if it has been called before. If not, then space for a new SV is allocated and the reference to the Perl -subroutine, C<name> is copied to the variable C<keepSub> in one -operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called +subroutine C<name> is copied to the variable C<keepSub> in one +operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called, the existing SV, C<keepSub>, is overwritten with the new value using C<SvSetSV>. @@ -1170,7 +1173,7 @@ to it. foreach (@list) { print "$_\n" } } -and here is an example of I<call_argv> which will call +And here is an example of I<call_argv> which will call I<PrintList>. static char * words[] = {"alpha", "beta", "gamma", "delta", NULL}; @@ -1188,7 +1191,7 @@ This is because I<call_argv> will do it for you. =head2 Using call_method -Consider the following Perl code +Consider the following Perl code: { package Mine; @@ -1216,7 +1219,7 @@ It implements just a very simple class to manage an array. Apart from the constructor, C<new>, it declares methods, one static and one virtual. The static method, C<PrintID>, prints out simply the class name and a version number. The virtual method, C<Display>, prints out a -single element of the array. Here is an all Perl example of using it. +single element of the array. Here is an all-Perl example of using it. $a = Mine->new('red', 'green', 'blue'); $a->Display(1); @@ -1228,22 +1231,22 @@ will print This is Class Mine version 1.0 Calling a Perl method from C is fairly straightforward. The following -things are required +things are required: =over 5 =item * -a reference to the object for a virtual method or the name of the class -for a static method. +A reference to the object for a virtual method or the name of the class +for a static method =item * -the name of the method. +The name of the method =item * -any other parameters specific to the method. +Any other parameters specific to the method =back @@ -1275,13 +1278,13 @@ the C<PrintID> and C<Display> methods from C. call_method(method, G_DISCARD); -So the methods C<PrintID> and C<Display> can be invoked like this +So the methods C<PrintID> and C<Display> can be invoked like this: $a = Mine->new('red', 'green', 'blue'); call_Method($a, 'Display', 1); call_PrintID('Mine', 'PrintID'); -The only thing to note is that in both the static and virtual methods, +The only thing to note is that, in both the static and virtual methods, the method name is not passed via the stack--it is used as the first parameter to I<call_method>. @@ -1301,7 +1304,7 @@ currently executing. else printf ("Context is Array\n"); -and here is some Perl to test it +And here is some Perl to test it. PrintContext; $a = PrintContext; @@ -1313,22 +1316,21 @@ The output from that will be Context is Scalar Context is Array -=head2 Using Perl to dispose of temporaries +=head2 Using Perl to Dispose of Temporaries In the examples given to date, any temporaries created in the callback (i.e., parameters passed on the stack to the I<call_*> function or -values returned via the stack) have been freed by one of these methods +values returned via the stack) have been freed by one of these methods: =over 5 =item * -specifying the G_DISCARD flag with I<call_*>. +Specifying the G_DISCARD flag with I<call_*> =item * -explicitly disposed of using the C<ENTER>/C<SAVETMPS> - -C<FREETMPS>/C<LEAVE> pairing. +Explicitly using the C<ENTER>/C<SAVETMPS>--C<FREETMPS>/C<LEAVE> pairing =back @@ -1413,7 +1415,7 @@ So what is the big problem? Well, if you are expecting Perl to tidy up those temporaries for you, you might be in for a long wait. For Perl to dispose of your temporaries, control must drop back to the enclosing scope at some stage. In the event driven scenario that may -never happen. This means that as time goes on, your program will +never happen. This means that, as time goes on, your program will create more and more temporaries, none of which will ever be freed. As each of these temporaries consumes some memory your program will eventually consume all the available memory in your system--kapow! @@ -1425,7 +1427,7 @@ any temporaries you may have created. Mind you, if you are at all uncertain about what to do, it doesn't do any harm to tidy up anyway. -=head2 Strategies for storing Callback Context Information +=head2 Strategies for Storing Callback Context Information Potentially one of the trickiest problems to overcome when designing a @@ -1779,15 +1781,15 @@ returned from Perl subroutines, it is also possible to bypass these macros and read the stack using the C<ST> macro (See L<perlxs> for a full description of the C<ST> macro). -Most of the time the C<POP*> macros should be adequate, the main +Most of the time the C<POP*> macros should be adequate; the main problem with them is that they force you to process the returned values in sequence. This may not be the most suitable way to process the values in some cases. What we want is to be able to access the stack in a random order. The C<ST> macro as used when coding an XSUB is ideal for this purpose. -The code below is the example given in the section I<Returning a list -of values> recoded to use C<ST> instead of C<POP*>. +The code below is the example given in the section I<Returning a List +of Values> recoded to use C<ST> instead of C<POP*>. static void call_AddSubtract2(a, b) @@ -1832,7 +1834,7 @@ Notes Notice that it was necessary to define the variable C<ax>. This is because the C<ST> macro expects it to exist. If we were in an XSUB it would not be necessary to define C<ax> as it is already defined for -you. +us. =item 2. @@ -1853,7 +1855,7 @@ refers to the last. =back -=head2 Creating and calling an anonymous subroutine in C +=head2 Creating and Calling an Anonymous Subroutine in C As we've already shown, C<call_sv> can be used to invoke an anonymous subroutine. However, our example showed a Perl script diff --git a/Master/tlpkg/tlperl/lib/pods/perlce.pod b/Master/tlpkg/tlperl/lib/pods/perlce.pod index 25cef84af67..2ca2bf0ae60 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlce.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlce.pod @@ -132,7 +132,7 @@ archive. NOTE: during a build there could be created a number (or one) of C<Config.pm> for cross-compilation ("foreign" C<Config.pm>) and those are hidden inside -C<../xlib/$(CROSS_NAME)> with other auxilary files, but, and this is important to +C<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to note, there should be B<no> C<Config.pm> for host miniperl. If you'll get an error that perl could not find Config.pm somewhere in building process this means something went wrong. Most probably you forgot to @@ -160,7 +160,7 @@ works on non-hpc devices. The simple stdio implementation creates the files C<stdin.txt>, C<stdout.txt> and C<stderr.txt>, so you might examine them if your -console has only a liminted number of cols. +console has only a limited number of cols. When exitcode is non-zero, a message box appears, otherwise the console closes, so you might have to catch an exit with diff --git a/Master/tlpkg/tlperl/lib/pods/perlcheat.pod b/Master/tlpkg/tlperl/lib/pods/perlcheat.pod index 7f2c83066f6..d210fa0a90b 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlcheat.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlcheat.pod @@ -88,6 +88,18 @@ Juerd Waalboer <#####@juerd.nl>, with the help of many Perl Monks. =head1 SEE ALSO - http://perlmonks.org/?node_id=216602 the original PM post - http://perlmonks.org/?node_id=238031 Damian Conway's Perl 6 version - http://juerd.nl/site.plp/perlcheat home of the Perl Cheat Sheet +=over 4 + +=item * + +L<http://perlmonks.org/?node_id=216602> - the original PM post + +=item * + +L<http://perlmonks.org/?node_id=238031> - Damian Conway's Perl 6 version + +=item * + +L<http://juerd.nl/site.plp/perlcheat> - home of the Perl Cheat Sheet + +=back diff --git a/Master/tlpkg/tlperl/lib/pods/perlclib.pod b/Master/tlpkg/tlperl/lib/pods/perlclib.pod index 1fe4699be1b..0785577dace 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlclib.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlclib.pod @@ -138,7 +138,7 @@ pattern into it that should be illegal as pointers (and floating point numbers), and also hopefully surprising enough as integers, so that any code attempting to use the data without forethought will break sooner rather than later. Poisoning can be done using the Poison() -macros, which have similar arguments as Zero(): +macros, which have similar arguments to Zero(): PoisonWith(dst, n, t, b) scribble memory with byte b PoisonNew(dst, n, t) equal to PoisonWith(dst, n, t, 0xAB) diff --git a/Master/tlpkg/tlperl/lib/pods/perlcommunity.pod b/Master/tlpkg/tlperl/lib/pods/perlcommunity.pod index 8430c3fcc10..96c7b85486e 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlcommunity.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlcommunity.pod @@ -14,15 +14,15 @@ evidence that the Perl users apply TMTOWTDI to all endeavors, not just programming. From websites, to IRC, to mailing lists, there is more than one way to get involved in the community. -=head2 Where to find the community +=head2 Where to Find the Community There is a central directory for the Perl community: L<http://perl.org> maintained by the Perl Foundation (L<http://www.perlfoundation.org/>), which tracks and provides services for a variety of other community sites. -=head2 Mailing lists and Newsgroups +=head2 Mailing Lists and Newsgroups -Perl runs on e-mail, there is no doubt about it. The Camel book was originally +Perl runs on e-mail; there is no doubt about it. The Camel book was originally written mostly over e-mail and today Perl's development is co-ordinated through mailing lists. The largest repository of Perl mailing lists is located at L<http://lists.perl.org>. @@ -41,7 +41,7 @@ The Perl community has a rather large IRC presence. For starters, it has its own IRC network, L<irc://irc.perl.org>. General (not help-oriented) chat can be found at L<irc://irc.perl.org/#perl>. Many other more specific chats are also hosted on the network. Information about irc.perl.org is located on the -network's website: L<http://www.irc.perl.org>. For a more help oriented #perl, +network's website: L<http://www.irc.perl.org>. For a more help-oriented #perl, check out L<irc://irc.freenode.net/#perl>. Perl 6 development also has a presence in L<irc://irc.freenode.net/#perl6>. Most Perl-related channels will be kind enough to point you in the right direction if you ask nicely. @@ -52,7 +52,7 @@ with varying activity levels. =head2 Websites Perl websites come in a variety of forms, but they fit into two large -categories: forums and news websites. There are many Perl related +categories: forums and news websites. There are many Perl-related websites, so only a few of the community's largest are mentioned here. =head3 News sites @@ -61,7 +61,7 @@ websites, so only a few of the community's largest are mentioned here. =item L<http://perl.com/> -Run by O'Reilly Media (The publisher of L<the Camel Book|perlbook> among other +Run by O'Reilly Media (the publisher of L<the Camel Book|perlbook>, among other Perl-related literature), perl.com provides current Perl news, articles, and resources for Perl developers as well as a directory of other useful websites. @@ -119,7 +119,7 @@ L<irc://irc.perl.org/#perl>. If you have never been to a hackathon, here are a few basic things you need to know before attending: have a working laptop and know how to use it; check out -the involved projects before hand; have the necessary version control client; +the involved projects beforehand; have the necessary version control client; and bring backup equipment (an extra LAN cable, additional power strips, etc.) because someone will forget. diff --git a/Master/tlpkg/tlperl/lib/pods/perlcompile.pod b/Master/tlpkg/tlperl/lib/pods/perlcompile.pod index 505ce68384f..dc829f45efd 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlcompile.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlcompile.pod @@ -77,9 +77,9 @@ This is why all the back ends print: before producing any other output. -=head2 The Cross Referencing Back End +=head2 The Cross-Referencing Back End -The cross referencing back end (B::Xref) produces a report on your program, +The cross-referencing back end (B::Xref) produces a report on your program, breaking down declarations and uses of subroutines and variables (and formats) by file and subroutine. For instance, here's part of the report from the I<pod2man> program that comes with Perl: @@ -215,7 +215,7 @@ This is like saying C<use O 'Deparse'> in your Perl program. This module prints a concise (but complete) version of the Perl parse tree. Its output is more customizable than the one of B::Terse or -B::Debug (and it can emulate them). This module useful for people who +B::Debug (and it can emulate them). This module is useful for people who are writing their own back end, or who are learning about the Perl internals. It's not useful to the average programmer. @@ -269,7 +269,7 @@ average programmer. This module prints a report on where the variables, subroutines, and formats are defined and used within a program and the modules it -loads. See L</"The Cross Referencing Back End"> for details about +loads. See L</"The Cross-Referencing Back End"> for details about usage. =back diff --git a/Master/tlpkg/tlperl/lib/pods/perlcygwin.pod b/Master/tlpkg/tlperl/lib/pods/perlcygwin.pod index 3933e562a47..713c2206793 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlcygwin.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlcygwin.pod @@ -27,7 +27,7 @@ platforms. They run thanks to the Cygwin library which provides the UNIX system calls and environment these programs expect. More information about this project can be found at: - F<http://www.cygwin.com/> +L<http://www.cygwin.com/> A recent net or commercial release of Cygwin is required. @@ -368,7 +368,7 @@ C<Cygwin::posix_to_win_path()>. Pathnames may not contain Unicode characters. C<Cygwin> still uses the ANSI API calls and no Unicode calls because of newlib deficiencies. There's an unofficial unicode patch for cygwin at -F<http://www.okisoft.co.jp/esc/utf8-cygwin/> +L<http://www.okisoft.co.jp/esc/utf8-cygwin/> =item * Text/Binary @@ -458,7 +458,7 @@ error like the following: Use the rebase utility to resolve the conflicting dll addresses. The rebase package is included in the Cygwin netrelease. Use setup.exe from -F<http://www.cygwin.com/setup.exe> to install it and run rebaseall. +L<http://www.cygwin.com/setup.exe> to install it and run rebaseall. =back @@ -563,17 +563,17 @@ be kept as clean as possible. pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod - pod/perltoc.pod pod.lst Porting/Glossary pod/perlrepository.pod + pod/perltoc.pod pod.lst Porting/Glossary pod/perlgit.pod Porting/checkAUTHORS.pl - ext/Compress-Raw-Zlib/Changes ext/Compress-Raw-Zlib/README - ext/Compress-Zlib/Changes cpan/Cwd/Changes ext/DB_File/Changes - ext/Encode/Changes ext/Sys-Syslog/Changes ext/Time-HiRes/Changes - ext/Win32API-File/Changes lib/CGI/Changes lib/ExtUtils/CBuilder/Changes - lib/ExtUtils/Changes lib/ExtUtils/NOTES lib/ExtUtils/PATCHING - lib/ExtUtils/README lib/Module/Build/Changes lib/Net/Ping/Changes - lib/Test/Harness/Changes - lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README - README.symbian symbian/TODO + dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes + ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes + ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes + ext/Time-HiRes/Changes ext/Win32API-File/Changes lib/CGI/Changes + lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes lib/ExtUtils/NOTES + lib/ExtUtils/PATCHING lib/ExtUtils/README lib/Module/Build/Changes + lib/Net/Ping/Changes lib/Test/Harness/Changes + lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README README.symbian + symbian/TODO =item Build, Configure, Make, Install @@ -673,7 +673,7 @@ be kept as clean as possible. lib/CPANPLUS/Internals/Constants/Report.pm - OS classifications lib/CPANPLUS/Internals/Constants.pm - - Contants for Cygwin + - Constants for Cygwin lib/CPANPLUS/Internals/Report.pm - Example of Cygwin report lib/CPANPLUS/Module.pm @@ -714,8 +714,8 @@ be kept as clean as possible. =item Perl Module Tests + dist/Cwd/t/cwd.t ext/Compress-Zlib/t/14gzopen.t - cpan/Cwd/t/cwd.t ext/DB_File/t/db-btree.t ext/DB_File/t/db-hash.t ext/DB_File/t/db-recno.t diff --git a/Master/tlpkg/tlperl/lib/pods/perldata.pod b/Master/tlpkg/tlperl/lib/pods/perldata.pod index bc564e650d4..1b1cbf4564b 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldata.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldata.pod @@ -52,7 +52,7 @@ X<scalar> $#days # the last index of array @days Entire arrays (and slices of arrays and hashes) are denoted by '@', -which works much like the word "these" or "those" does in English, +which works much as the word "these" or "those" does in English, in that it indicates multiple values are expected. X<array> @@ -140,7 +140,7 @@ to determine the context for the right argument. Assignment to a scalar evaluates the right-hand side in scalar context, while assignment to an array or hash evaluates the righthand side in list context. Assignment to a list (or slice, which is just a list -anyway) also evaluates the righthand side in list context. +anyway) also evaluates the right-hand side in list context. When you use the C<use warnings> pragma or Perl's B<-w> command-line option, you may see warnings @@ -276,8 +276,8 @@ set. For example, you stick 10,000 things in a hash, but evaluating %HASH in scalar context reveals C<"1/16">, which means only one out of sixteen buckets has been touched, and presumably contains all 10,000 of your items. This isn't supposed to happen. If a tied hash -is evaluated in scalar context, a fatal error will result, since this -bucket usage information is currently not available for tied hashes. +is evaluated in scalar context, the C<SCALAR> method is called (with a +fallback to C<FIRSTKEY>). X<hash, scalar context> X<hash, bucket> X<bucket> You can preallocate space for a hash by assigning to the keys() function. @@ -391,7 +391,7 @@ inet_aton()/inet_ntoa() routines of the Socket package. Note that since Perl 5.8.1 the single-number v-strings (like C<v65>) are not v-strings before the C<< => >> operator (which is usually used -to separate a hash key from a hash value), instead they are interpreted +to separate a hash key from a hash value); instead they are interpreted as literal strings ('v65'). They were v-strings from Perl 5.6.0 to Perl 5.8.0, but that caused more confusion and breakage than good. Multi-number v-strings like C<v65.66> and C<65.66.67> continue to @@ -406,7 +406,8 @@ represent the current filename, line number, and package name at that point in your program. They may be used only as separate tokens; they will not be interpolated into strings. If there is no current package (due to an empty C<package;> directive), __PACKAGE__ is the undefined -value. +value. (But the empty C<package;> is no longer supported, as of version +5.10.) X<__FILE__> X<__LINE__> X<__PACKAGE__> X<line> X<file> X<package> The two control characters ^D and ^Z, and the tokens __END__ and __DATA__ @@ -451,7 +452,7 @@ produces a compile-time error instead. The restriction lasts to the end of the enclosing block. An inner block may countermand this by saying C<no strict 'subs'>. -=head3 Array Joining Delimiter +=head3 Array Interpolation X<array, interpolation> X<interpolation, array> X<$"> Arrays and slices are interpolated into double-quoted strings @@ -667,7 +668,8 @@ of how to arrange for an output ordering. =head2 Subscripts -An array is subscripted by specifying a dollar sign (C<$>), then the +An array can be accessed one scalar at a +time by specifying a dollar sign (C<$>), then the name of the array (without the leading C<@>), then the subscript inside square brackets. For example: @@ -691,15 +693,12 @@ are used. For example: print "Darwin's First Name is ", $scientists{"Darwin"}, "\n"; -=head2 Slices -X<slice> X<array, slice> X<hash, slice> +You can also subscript a list to get a single element from it: -A common way to access an array or a hash is one scalar element at a -time. You can also subscript a list to get a single element from it. + $dir = (getpwnam("daemon"))[7]; - $whoami = $ENV{"USER"}; # one element from the hash - $parent = $ISA[0]; # one element from the array - $dir = (getpwnam("daemon"))[7]; # likewise, but with list +=head2 Slices +X<slice> X<array, slice> X<hash, slice> A slice accesses several elements of a list, an array, or a hash simultaneously using a list of subscripts. It's more convenient @@ -761,6 +760,13 @@ is the number of elements on the right-hand side of the assignment. The null list contains no elements, so when the password file is exhausted, the result is 0, not 2. +Slices in scalar context return the last item of the slice. + + @a = qw/first second third/; + %h = (first => 'A', second => 'B'); + $t = @a[0, 1]; # $t is now 'second' + $u = @h{'first', 'second'}; # $u is now 'B' + If you're confused about why you use an '@' there on a hash slice instead of a '%', think of it like this. The type of bracket (square or curly) governs whether it's an array or a hash being looked at. @@ -856,8 +862,8 @@ C<use strict 'refs'> forbids such practice. Another way to create anonymous filehandles is with the Symbol module or with the IO::Handle module and its ilk. These modules have the advantage of not hiding different types of the same name -during the local(). See the bottom of L<perlfunc/open()> for an -example. +during the local(). See the bottom of L<perlfunc/"open FILEHANDLE"> +for an example. =head1 SEE ALSO diff --git a/Master/tlpkg/tlperl/lib/pods/perldbmfilter.pod b/Master/tlpkg/tlperl/lib/pods/perldbmfilter.pod index e58ce2013be..2a4c2399558 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldbmfilter.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldbmfilter.pod @@ -17,7 +17,7 @@ The four C<filter_*> methods shown above are available in all the DBM modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File, ODBM_File and SDBM_File. -Each of the methods work identically, and are used to install (or +Each of the methods works identically, and is used to install (or uninstall) a single DBM Filter. The only difference between them is the place that the filter is installed. @@ -51,7 +51,7 @@ every time you read a value from a DBM database. You can use any combination of the methods from none to all four. All filter methods return the existing filter, if present, or C<undef> -in not. +if not. To delete a filter pass C<undef> to it. diff --git a/Master/tlpkg/tlperl/lib/pods/perldebguts.pod b/Master/tlpkg/tlperl/lib/pods/perldebguts.pod index 402b67c242f..9bc0b63de46 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldebguts.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldebguts.pod @@ -53,7 +53,7 @@ C<"$break_condition\0$action">. The same holds for evaluated strings that contain subroutines, or which are currently being executed. The $filename for C<eval>ed strings -looks like C<(eval 34)> or C<(re_eval 19)>. +looks like C<(eval 34)> or C<(re_eval 19)>. =item * @@ -151,9 +151,9 @@ after the debugger completes its own initialization.) After the rc file is read, the debugger reads the PERLDB_OPTS environment variable and uses it to set debugger options. The contents of this variable are treated as if they were the argument -of an C<o ...> debugger command (q.v. in L<perldebug/Options>). +of an C<o ...> debugger command (q.v. in L<perldebug/"Configurable Options">). -=head3 Debugger internal variables +=head3 Debugger Internal Variables In addition to the file and subroutine-related variables mentioned above, the debugger also maintains various magical internal variables. @@ -172,7 +172,7 @@ equal to zero only if the line is not breakable. =item * -C<%DB::dbline>, is an alias for C<%{"::_<current_file"}>, which +C<%DB::dbline> is an alias for C<%{"::_<current_file"}>, which contains breakpoints and actions keyed by line number in the currently-selected file, either explicitly chosen with the debugger's C<f> command, or implicitly by flow of execution. @@ -184,7 +184,7 @@ C<"$break_condition\0$action">. =back -=head3 Debugger customization functions +=head3 Debugger Customization Functions Some functions are provided to simplify customization. @@ -257,8 +257,8 @@ with this one, once the C<o>ption C<frame=2> has been set: By way of demonstration, we present below a laborious listing resulting from setting your C<PERLDB_OPTS> environment variable to the value C<f=n N>, and running I<perl -d -V> from the command line. -Examples use various values of C<n> are shown to give you a feel -for the difference between settings. Long those it may be, this +Examples using various values of C<n> are shown to give you a feel +for the difference between settings. Long though it may be, this is not a complete listing, but only excerpts. =over 4 @@ -397,7 +397,7 @@ When a package is compiled, a line like this is printed with proper indentation. -=head1 Debugging regular expressions +=head1 Debugging Regular Expressions There are two ways to enable debugging output for regular expressions. @@ -408,7 +408,7 @@ Otherwise, one can C<use re 'debug'>, which has effects at compile time and run time. Since Perl 5.9.5, this pragma is lexically scoped. -=head2 Compile-time output +=head2 Compile-time Output The debugging output at compile time looks like this: @@ -514,7 +514,7 @@ C<(??{ code })>. =item C<anchored(TYPE)> -If the pattern may match only at a handful of places, (with C<TYPE> +If the pattern may match only at a handful of places, with C<TYPE> being C<BOL>, C<MBOL>, or C<GPOS>. See the table below. =back @@ -532,119 +532,240 @@ form of the regex. Each line has format C< >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>) -=head2 Types of nodes +=head2 Types of Nodes Here are the possible types, with short descriptions: - # TYPE arg-description [num-args] [longjump-len] DESCRIPTION - - # Exit points - END no End of program. - SUCCEED no Return from a subroutine, basically. - - # Anchors: - BOL no Match "" at beginning of line. - MBOL no Same, assuming multiline. - SBOL no Same, assuming singleline. - EOS no Match "" at end of string. - EOL no Match "" at end of line. - MEOL no Same, assuming multiline. - SEOL no Same, assuming singleline. - BOUND no Match "" at any word boundary - BOUNDL no Match "" at any word boundary - NBOUND no Match "" at any word non-boundary - NBOUNDL no Match "" at any word non-boundary - GPOS no Matches where last m//g left off. - - # [Special] alternatives - ANY no Match any one character (except newline). - SANY no Match any one character. - ANYOF sv Match character in (or not in) this class. - ALNUM no Match any alphanumeric character - ALNUML no Match any alphanumeric char in locale - NALNUM no Match any non-alphanumeric character - NALNUML no Match any non-alphanumeric char in locale - SPACE no Match any whitespace character - SPACEL no Match any whitespace char in locale - NSPACE no Match any non-whitespace character - NSPACEL no Match any non-whitespace char in locale - DIGIT no Match any numeric character - NDIGIT no Match any non-numeric character - - # BRANCH The set of branches constituting a single choice are hooked - # together with their "next" pointers, since precedence prevents - # anything being concatenated to any individual branch. The - # "next" pointer of the last BRANCH in a choice points to the - # thing following the whole choice. This is also where the - # final "next" pointer of each individual branch points; each - # branch starts with the operand node of a BRANCH node. - # - BRANCH node Match this alternative, or the next... - - # BACK Normal "next" pointers all implicitly point forward; BACK - # exists to make loop structures possible. - # not used - BACK no Match "", "next" ptr points backward. - - # Literals - EXACT sv Match this string (preceded by length). - EXACTF sv Match this string, folded (prec. by length). - EXACTFL sv Match this string, folded in locale (w/len). - - # Do nothing - NOTHING no Match empty string. - # A variant of above which delimits a group, thus stops optimizations - TAIL no Match empty string. Can jump here from outside. - - # STAR,PLUS '?', and complex '*' and '+', are implemented as circular - # BRANCH structures using BACK. Simple cases (one character - # per match) are implemented with STAR and PLUS for speed - # and to minimize recursive plunges. - # - STAR node Match this (simple) thing 0 or more times. - PLUS node Match this (simple) thing 1 or more times. - - CURLY sv 2 Match this simple thing {n,m} times. - CURLYN no 2 Match next-after-this simple thing - # {n,m} times, set parens. - CURLYM no 2 Match this medium-complex thing {n,m} times. - CURLYX sv 2 Match this complex thing {n,m} times. - - # This terminator creates a loop structure for CURLYX - WHILEM no Do curly processing and see if rest matches. - - # OPEN,CLOSE,GROUPP ...are numbered at compile time. - OPEN num 1 Mark this point in input as start of #n. - CLOSE num 1 Analogous to OPEN. - - REF num 1 Match some already matched string - REFF num 1 Match already matched string, folded - REFFL num 1 Match already matched string, folded in loc. - - # grouping assertions - IFMATCH off 1 2 Succeeds if the following matches. - UNLESSM off 1 2 Fails if the following matches. - SUSPEND off 1 1 "Independent" sub-regex. - IFTHEN off 1 1 Switch, should be preceded by switcher . - GROUPP num 1 Whether the group matched. - - # Support for long regex - LONGJMP off 1 1 Jump far away. - BRANCHJ off 1 1 BRANCH with long offset. - - # The heavy worker - EVAL evl 1 Execute some Perl code. - - # Modifiers - MINMOD no Next operator is not greedy. - LOGICAL no Next opcode should set the flag only. - - # This is not used yet - RENUM off 1 1 Group with independently numbered parens. - - # This is not really a node, but an optimized away piece of a "long" node. - # To simplify debugging output, we mark it as if it were a node - OPTIMIZED off Placeholder for dump. + # TYPE arg-description [num-args] [longjump-len] DESCRIPTION + + # Exit points + END no End of program. + SUCCEED no Return from a subroutine, basically. + + # Anchors: + + BOL no Match "" at beginning of line. + MBOL no Same, assuming multiline. + SBOL no Same, assuming singleline. + EOS no Match "" at end of string. + EOL no Match "" at end of line. + MEOL no Same, assuming multiline. + SEOL no Same, assuming singleline. + BOUND no Match "" at any word boundary using native charset + semantics for non-utf8 + BOUNDL no Match "" at any locale word boundary + BOUNDU no Match "" at any word boundary using Unicode semantics + BOUNDA no Match "" at any word boundary using ASCII semantics + NBOUND no Match "" at any word non-boundary using native charset + semantics for non-utf8 + NBOUNDL no Match "" at any locale word non-boundary + NBOUNDU no Match "" at any word non-boundary using Unicode semantics + NBOUNDA no Match "" at any word non-boundary using ASCII semantics + GPOS no Matches where last m//g left off. + + # [Special] alternatives: + + REG_ANY no Match any one character (except newline). + SANY no Match any one character. + CANY no Match any one byte. + ANYOF sv Match character in (or not in) this class, single char + match only + ANYOFV sv Match character in (or not in) this class, can + match-multiple chars + ALNUM no Match any alphanumeric character using native charset + semantics for non-utf8 + ALNUML no Match any alphanumeric char in locale + ALNUMU no Match any alphanumeric char using Unicode semantics + ALNUMA no Match [A-Za-z_0-9] + NALNUM no Match any non-alphanumeric character using native charset + semantics for non-utf8 + NALNUML no Match any non-alphanumeric char in locale + NALNUMU no Match any non-alphanumeric char using Unicode semantics + NALNUMA no Match [^A-Za-z_0-9] + SPACE no Match any whitespace character using native charset + semantics for non-utf8 + SPACEL no Match any whitespace char in locale + SPACEU no Match any whitespace char using Unicode semantics + SPACEA no Match [ \t\n\f\r] + NSPACE no Match any non-whitespace character using native charset + semantics for non-utf8 + NSPACEL no Match any non-whitespace char in locale + NSPACEU no Match any non-whitespace char using Unicode semantics + NSPACEA no Match [^ \t\n\f\r] + DIGIT no Match any numeric character using native charset semantics + for non-utf8 + DIGITL no Match any numeric character in locale + DIGITA no Match [0-9] + NDIGIT no Match any non-numeric character using native charset + i semantics for non-utf8 + NDIGITL no Match any non-numeric character in locale + NDIGITA no Match [^0-9] + CLUMP no Match any extended grapheme cluster sequence + + # Alternation + + # BRANCH The set of branches constituting a single choice are hooked + # together with their "next" pointers, since precedence prevents + # anything being concatenated to any individual branch. The + # "next" pointer of the last BRANCH in a choice points to the + # thing following the whole choice. This is also where the + # final "next" pointer of each individual branch points; each + # branch starts with the operand node of a BRANCH node. + # + BRANCH node Match this alternative, or the next... + + # Back pointer + + # BACK Normal "next" pointers all implicitly point forward; BACK + # exists to make loop structures possible. + # not used + BACK no Match "", "next" ptr points backward. + + # Literals + + EXACT str Match this string (preceded by length). + EXACTF str Match this string, folded, native charset semantics for + non-utf8 (prec. by length). + EXACTFL str Match this string, folded in locale (w/len). + EXACTFU str Match this string, folded, Unicode semantics for non-utf8 + (prec. by length). + EXACTFA str Match this string, folded, Unicode semantics for non-utf8, + but no ASCII-range character matches outside ASCII (prec. + by length),. + + # Do nothing types + + NOTHING no Match empty string. + # A variant of above which delimits a group, thus stops optimizations + TAIL no Match empty string. Can jump here from outside. + + # Loops + + # STAR,PLUS '?', and complex '*' and '+', are implemented as circular + # BRANCH structures using BACK. Simple cases (one character + # per match) are implemented with STAR and PLUS for speed + # and to minimize recursive plunges. + # + STAR node Match this (simple) thing 0 or more times. + PLUS node Match this (simple) thing 1 or more times. + + CURLY sv 2 Match this simple thing {n,m} times. + CURLYN no 2 Capture next-after-this simple thing + CURLYM no 2 Capture this medium-complex thing {n,m} times. + CURLYX sv 2 Match this complex thing {n,m} times. + + # This terminator creates a loop structure for CURLYX + WHILEM no Do curly processing and see if rest matches. + + # Buffer related + + # OPEN,CLOSE,GROUPP ...are numbered at compile time. + OPEN num 1 Mark this point in input as start of #n. + CLOSE num 1 Analogous to OPEN. + + REF num 1 Match some already matched string + REFF num 1 Match already matched string, folded using native charset + semantics for non-utf8 + REFFL num 1 Match already matched string, folded in loc. + REFFU num 1 Match already matched string, folded using unicode + semantics for non-utf8 + REFFA num 1 Match already matched string, folded using unicode + semantics for non-utf8, no mixing ASCII, non-ASCII + + # Named references. Code in regcomp.c assumes that these all are after the + # numbered references + NREF no-sv 1 Match some already matched string + NREFF no-sv 1 Match already matched string, folded using native charset + semantics for non-utf8 + NREFFL no-sv 1 Match already matched string, folded in loc. + NREFFU num 1 Match already matched string, folded using unicode + semantics for non-utf8 + NREFFA num 1 Match already matched string, folded using unicode + semantics for non-utf8, no mixing ASCII, non-ASCII + + IFMATCH off 1 2 Succeeds if the following matches. + UNLESSM off 1 2 Fails if the following matches. + SUSPEND off 1 1 "Independent" sub-RE. + IFTHEN off 1 1 Switch, should be preceded by switcher. + GROUPP num 1 Whether the group matched. + + # Support for long RE + + LONGJMP off 1 1 Jump far away. + BRANCHJ off 1 1 BRANCH with long offset. + + # The heavy worker + + EVAL evl 1 Execute some Perl code. + + # Modifiers + + MINMOD no Next operator is not greedy. + LOGICAL no Next opcode should set the flag only. + + # This is not used yet + RENUM off 1 1 Group with independently numbered parens. + + # Trie Related + + # Behave the same as A|LIST|OF|WORDS would. The '..C' variants have + # inline charclass data (ascii only), the 'C' store it in the structure. + # NOTE: the relative order of the TRIE-like regops is significant + + TRIE trie 1 Match many EXACT(F[ALU]?)? at once. flags==type + TRIEC charclass Same as TRIE, but with embedded charclass data + + # For start classes, contains an added fail table. + AHOCORASICK trie 1 Aho Corasick stclass. flags==type + AHOCORASICKC charclass Same as AHOCORASICK, but with embedded charclass data + + # Regex Subroutines + GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs arg2 + GOSTART no recurse to start of pattern + + # Special conditionals + NGROUPP no-sv 1 Whether the group matched. + INSUBP num 1 Whether we are in a specific recurse. + DEFINEP none 1 Never execute directly. + + # Backtracking Verbs + ENDLIKE none Used only for the type field of verbs + OPFAIL none Same as (?!) + ACCEPT parno 1 Accepts the current matched string. + + + # Verbs With Arguments + VERB no-sv 1 Used only for the type field of verbs + PRUNE no-sv 1 Pattern fails at this startpoint if no-backtracking through this + MARKPOINT no-sv 1 Push the current location for rollback by cut. + SKIP no-sv 1 On failure skip forward (to the mark) before retrying + COMMIT no-sv 1 Pattern fails outright if backtracking through this + CUTGROUP no-sv 1 On failure go to the next alternation in the group + + # Control what to keep in $&. + KEEPS no $& begins here. + + # New charclass like patterns + LNBREAK none generic newline pattern + VERTWS none vertical whitespace (Perl 6) + NVERTWS none not vertical whitespace (Perl 6) + HORIZWS none horizontal whitespace (Perl 6) + NHORIZWS none not horizontal whitespace (Perl 6) + + FOLDCHAR codepoint 1 codepoint with tricky case folding properties. + + # SPECIAL REGOPS + + # This is not really a node, but an optimized away piece of a "long" node. + # To simplify debugging output, we mark it as if it were a node + OPTIMIZED off Placeholder for dump. + + # Special opcode with the property that no opcode in a compiled program + # will ever be of this type. Thus it can be used as a flag value that + # no other opcode has been seen. END is used similarly, in that an END + # node cant be optimized. So END implies "unoptimizable" and PSEUDO mean + # "not seen anything to optimize yet". + PSEUDO off Pseudo opcode for internal use. =for unprinted-credits Next section M-J. Dominus (mjd-perl-patch+@plover.com) 20010421 @@ -676,7 +797,7 @@ is, it corresponds to the C<+> symbol in the precompiled regex. C<0[0]> items indicate that there is no corresponding node. -=head2 Run-time output +=head2 Run-time Output First of all, when doing a match, one may get no run-time output even if debugging is enabled. This means that the regex engine was never @@ -719,7 +840,7 @@ C< >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>> |I<ID>: I<TYPE> The I<TYPE> info is indented with respect to the backtracking level. Other incidental information appears interspersed within. -=head1 Debugging Perl memory usage +=head1 Debugging Perl Memory Usage Perl is a profligate wastrel when it comes to memory use. There is a saying that to estimate memory usage of Perl, assume a reasonable @@ -755,7 +876,7 @@ The B<-DL> command-line switch is obsolete since circa Perl 5.6.0 The switch was used to track Perl's memory allocations and possible memory leaks. These days the use of malloc debugging tools like F<Purify> or F<valgrind> is suggested instead. See also -L<perlhack/PERL_MEM_LOG>. +L<perlhacktips/PERL_MEM_LOG>. One way to find out how much memory is being used by Perl data structures is to install the Devel::Size module from CPAN: it gives @@ -764,7 +885,7 @@ structure. Please be mindful of the difference between the size() and total_size(). If Perl has been compiled using Perl's malloc you can analyze Perl -memory usage by setting the $ENV{PERL_DEBUG_MSTATS}. +memory usage by setting $ENV{PERL_DEBUG_MSTATS}. =head2 Using C<$ENV{PERL_DEBUG_MSTATS}> @@ -812,7 +933,7 @@ would have usable size 8188, and the memory footprint would be 8192. In a Perl built for debugging, some buckets may have negative usable size. This means that these buckets cannot (and will not) be used. For larger buckets, the memory footprint may be one page greater -than a power of 2. If so, case the corresponding power of two is +than a power of 2. If so, the corresponding power of two is printed in the C<APPROX> field above. =item Free/Used @@ -830,7 +951,7 @@ were free: 8 16 32 64 128 256 512 1024 2048 4096 8192 4 12 24 48 80 -With non-C<DEBUGGING> perl, the buckets starting from C<128> have +With a non-C<DEBUGGING> perl, the buckets starting from C<128> have a 4-byte overhead, and thus an 8192-long bucket may take up to 8188-byte allocations. diff --git a/Master/tlpkg/tlperl/lib/pods/perldebtut.pod b/Master/tlpkg/tlperl/lib/pods/perldebtut.pod index b10f9b4066e..77b86905351 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldebtut.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldebtut.pod @@ -512,7 +512,7 @@ using the list 'L' command: 17: print "$out $deg\n"; break if (1) -Note that to delete a breakpoint you use 'd' or 'D'. +Note that to delete a breakpoint you use 'B'. Now we'll continue down into our subroutine, this time rather than by line number, we'll use the subroutine name, followed by the now familiar 'v': diff --git a/Master/tlpkg/tlperl/lib/pods/perldebug.pod b/Master/tlpkg/tlperl/lib/pods/perldebug.pod index 9e67b4df422..8fbb2312ad4 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldebug.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldebug.pod @@ -9,7 +9,7 @@ First of all, have you tried using the B<-w> switch? If you're new to the Perl debugger, you may prefer to read -L<perldebtut>, which is a tutorial introduction to the debugger . +L<perldebtut>, which is a tutorial introduction to the debugger. =head1 The Perl Debugger @@ -54,7 +54,7 @@ function with something that doesn't look like a debugger command, such as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses or braces. -=head2 Calling the debugger +=head2 Calling the Debugger There are several ways to call the debugger: @@ -388,7 +388,7 @@ Delete all watch-expressions. =item o X<debugger command, o> -Display all options +Display all options. =item o booloption ... X<debugger command, o> @@ -589,7 +589,7 @@ blessed object, or to a package name. =item M X<debugger command, M> -Displays all loaded modules and their versions +Display all loaded modules and their versions. =item man [manpage] @@ -654,7 +654,7 @@ X<debugger option, dieLevel> Level of verbosity. By default, the debugger leaves your exceptions and warnings alone, because altering them can break correctly running programs. It will attempt to print a message when uncaught INT, BUS, or -SEGV signals arrive. (But see the mention of signals in L<BUGS> below.) +SEGV signals arrive. (But see the mention of signals in L</BUGS> below.) To disable this default safe mode, set these values to something higher than 0. At a level of 1, you get backtraces upon receiving any kind @@ -876,7 +876,7 @@ corresponds to F</dev/ttyXX>, say, by issuing a command like See L<perldebguts/"Debugger Internals"> for details. -=head2 Debugger input/output +=head2 Debugger Input/Output =over 8 @@ -942,7 +942,7 @@ also from I<camel_flea>, but from line 4. If you execute the C<T> command from inside an active C<use> statement, the backtrace will contain both a C<require> frame and -an C<eval>) frame. +an C<eval> frame. =item Line Listing Format @@ -977,12 +977,12 @@ for incredibly long examples of these. =back -=head2 Debugging compile-time statements +=head2 Debugging Compile-Time Statements If you have compile-time executable statements (such as code within BEGIN, UNITCHECK and CHECK blocks or C<use> statements), these will I<not> be stopped by debugger, although C<require>s and INIT blocks -will, and compile-time statements can be traced with C<AutoTrace> +will, and compile-time statements can be traced with the C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl code, however, you can transfer control back to the debugger using the following statement, which is harmless if the debugger is not running: @@ -1007,7 +1007,7 @@ compile subname> for the same purpose. The debugger probably contains enough configuration hooks that you won't ever have to modify it yourself. You may change the behaviour -of debugger from within the debugger using its C<o> command, from +of the debugger from within the debugger using its C<o> command, from the command line via the C<PERLDB_OPTS> environment variable, and from customization files. @@ -1056,13 +1056,13 @@ Note that any variables and functions that are not documented in this document (or in L<perldebguts>) are considered for internal use only, and as such are subject to change without notice. -=head2 Readline Support / History in the debugger +=head2 Readline Support / History in the Debugger As shipped, the only command-line history supplied is a simplistic one that checks for leading exclamation points. However, if you install the Term::ReadKey and Term::ReadLine modules from CPAN (such as Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will -have full editing capabilities much like GNU I<readline>(3) provides. +have full editing capabilities much like those GNU I<readline>(3) provides. Look for these in the F<modules/by-module/Term> directory on CPAN. These do not support normal B<vi> command-line editing, however. @@ -1080,9 +1080,10 @@ it can interact with the Perl debugger to provide an integrated software development environment reminiscent of its interactions with C debuggers. -Perl comes with a start file for making B<emacs> act like a +Recent versions of Emacs come with a +start file for making B<emacs> act like a syntax-directed editor that understands (some of) Perl's syntax. -Look in the I<emacs> directory of the Perl source distribution. +See L<perlfaq3>. A similar setup by Tom Christiansen for interacting with any vendor-shipped B<vi> and the X11 window system is also available. @@ -1117,7 +1118,7 @@ interpret the information in that profile. More powerful profilers, such as C<Devel::NYTProf> are available from the CPAN: see L<perlperf> for details. -=head1 Debugging regular expressions +=head1 Debugging Regular Expressions X<regular expression, debugging> X<regex, debugging> X<regexp, debugging> @@ -1127,15 +1128,15 @@ voluminous output, one must not only have some idea about how regular expression matching works in general, but also know how Perl's regular expressions are internally compiled into an automaton. These matters are explored in some detail in -L<perldebguts/"Debugging regular expressions">. +L<perldebguts/"Debugging Regular Expressions">. -=head1 Debugging memory usage +=head1 Debugging Memory Usage X<memory usage> Perl contains internal support for reporting its own memory usage, but this is a fairly advanced concept that requires some understanding of how memory allocation works. -See L<perldebguts/"Debugging Perl memory usage"> for the details. +See L<perldebguts/"Debugging Perl Memory Usage"> for the details. =head1 SEE ALSO diff --git a/Master/tlpkg/tlperl/lib/pods/perldelta.pod b/Master/tlpkg/tlperl/lib/pods/perldelta.pod index 20d38bb15ca..425708fbb46 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldelta.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldelta.pod @@ -2,82 +2,208 @@ =head1 NAME -perldelta - what is new for perl v5.12.3 +perldelta - what is new for perl v5.14.2 =head1 DESCRIPTION -This document describes differences between the 5.12.2 release and -the 5.12.3 release. +This document describes differences between the 5.14.1 release and +the 5.14.2 release. -If you are upgrading from an earlier release such as 5.12.1, first read -L<perl5122delta>, which describes differences between 5.12.1 and -5.12.2. The major changes made in 5.12.0 are described in L<perl5120delta>. +If you are upgrading from an earlier release such as 5.14.0, first read +L<perl5141delta>, which describes differences between 5.14.0 and +5.14.1. + +=head1 Core Enhancements + +No changes since 5.14.0. + +=head1 Security + +=head2 C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC (CVE-2011-2728). + +Calling C<File::Glob::bsd_glob> with the unsupported flag GLOB_ALTDIRFUNC would +cause an access violation / segfault. A Perl program that accepts a flags value from +an external source could expose itself to denial of service or arbitrary code +execution attacks. There are no known exploits in the wild. The problem has been +corrected by explicitly disabling all unsupported flags and setting unused function +pointers to null. Bug reported by Clément Lecigne. + +=head2 C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939) + +A bug in C<Encode> could, on certain inputs, cause the heap to overflow. +This problem has been corrected. Bug reported by Robert Zacek. =head1 Incompatible Changes - There are no changes intentionally incompatible with 5.12.2. If any - exist, they are bugs and reports are welcome. +There are no changes intentionally incompatible with 5.14.0. If any +exist, they are bugs and reports are welcome. -=head1 Core Enhancements +=head1 Deprecations -=head2 C<keys>, C<values> work on arrays +There have been no deprecations since 5.14.0. -You can now use the C<keys>, C<values>, C<each> builtin functions on arrays -(previously you could only use them on hashes). See L<perlfunc> for details. -This is actually a change introduced in perl 5.12.0, but it was missed from -that release's perldelta. +=head1 Modules and Pragmata -=head1 Bug Fixes +=head2 New Modules and Pragmata + +None + +=head2 Updated Modules and Pragmata + +=over 4 + +=item * + +L<CPAN> has been upgraded from version 1.9600 to version 1.9600_01. + +L<CPAN::Distribution> has been upgraded from version 1.9602 to 1.9602_01. + +Backported bugfixes from CPAN version 1.9800. Ensures proper +detection of C<configure_requires> prerequisites from CPAN Meta files +in the case where C<dynamic_config> is true. [rt.cpan.org #68835] + +Also ensures that C<configure_requires> is only checked in META files, +not MYMETA files, so protect against MYMETA generation that drops +C<configure_requires>. + +=item * + +L<Encode> has been upgraded from version 2.42 to 2.42_01. + +See L</Security>. + +=item * + +L<File::Glob> has been upgraded from version 1.12 to version 1.13. + +See L</Security>. + +=item * + +L<PerlIO::scalar> has been upgraded from version 0.11 to 0.11_01. + +It fixes a problem with C<< open my $fh, ">", \$scalar >> not working if +C<$scalar> is a copy-on-write scalar. + +=back + +=head2 Removed Modules and Pragmata + +None -"no VERSION" will now correctly deparse with B::Deparse, as will certain -constant expressions. +=head1 Platform Support -Module::Build should be more reliably pass its tests under cygwin. +=head2 New Platforms -lvalue sub return values are now COW. +None -=head1 Platform Specific Notes +=head2 Discontinued Platforms + +None + +=head2 Platform-Specific Notes + +=over 4 + +=item HP-UX PA-RISC/64 now supports gcc-4.x + +A fix to correct the socketsize now makes the test suite pass on HP-UX +PA-RISC for 64bitall builds. + +=item Building on OS X 10.7 Lion and Xcode 4 works again + +The build system has been updated to work with the build tools under Mac OS X +10.7. + +=back + +=head1 Bug Fixes =over 4 -=item Solaris +=item * + +In @INC filters (subroutines returned by subroutines in @INC), $_ used to +misbehave: If returned from a subroutine, it would not be copied, but the +variable itself would be returned; and freeing $_ (e.g., with C<undef *_>) +would cause perl to crash. This has been fixed [perl #91880]. + +=item * + +Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of +a pack template equivalent to "U0" if the input string was empty. This has +been fixed [perl #90160]. + +=item * -A separate DTrace is now build for miniperl, which means that perl can be -compiled with -Dusedtrace on Solaris again. +C<caller> no longer leaks memory when called from the DB package if +C<@DB::args> was assigned to after the first call to C<caller>. L<Carp> +was triggering this bug [perl #97010]. -=item VMS +=item * + +C<utf8::decode> had a nasty bug that would modify copy-on-write scalars' +string buffers in place (i.e., skipping the copy). This could result in +hashes having two elements with the same key [perl #91834]. + +=item * + +Localising a tied variable used to make it read-only if it contained a +copy-on-write string. + +=item * + +Elements of restricted hashes (see the L<fields> pragma) containing +copy-on-write values couldn't be deleted, nor could such hashes be cleared +(C<%hash = ()>). + +=item * + +Locking a hash element that is a glob copy no longer causes subsequent +assignment to it to corrupt the glob. + +=item * + +A panic involving the combination of the regular expression modifiers +C</aa> introduced in 5.14.0 and the C<\b> escape sequence has been +fixed [perl #95964]. + +=back + +=head1 Known Problems + +This is a list of some significant unfixed bugs, which are regressions +from 5.12.0. + +=over 4 -A number of regressions on VMS have been fixed. In addition to minor cleanup -of questionable expressions in F<vms.c>, file permissions should no longer be -garbled by the PerlIO layer, and spurious record boundaries should no longer be -introduced by the PerlIO layer during output. +=item * -For more details and discussion on the latter, see: +C<PERL_GLOBAL_STRUCT> is broken. - http://www.nntp.perl.org/group/perl.vmsperl/2010/11/msg15419.html +Since perl 5.14.0, building with C<-DPERL_GLOBAL_STRUCT> hasn't been +possible. This means that perl currently doesn't work on any platforms that +require it to be built this way, including Symbian. -=item VOS +While C<PERL_GLOBAL_STRUCT> now works again on recent development versions of +perl, it actually working on Symbian again hasn't been verified. -A few very small changes were made to the build process on VOS to better -support the platform. Longer-than-32-character filenames are now supported on -OpenVOS, and build properly without IPv6 support. +We'd be very interested in hearing from anyone working with Perl on Symbian. =back =head1 Acknowledgements -Perl 5.12.3 represents approximately four months of development since -Perl 5.12.2 and contains approximately 2500 lines of changes across -54 files from 16 authors. +Perl 5.14.2 represents approximately three months of development since +Perl 5.14.1 and contains approximately 1200 lines of changes +across 61 files from 9 authors. Perl continues to flourish into its third decade thanks to a vibrant community of users and developers. The following people are known to -have contributed the improvements that became Perl 5.12.3: +have contributed the improvements that became Perl 5.14.2: -Craig A. Berry, David Golden, David Leadbeater, Father Chrysostomos, Florian -Ragwitz, Jesse Vincent, Karl Williamson, Nick Johnston, Nicolas Kaiser, Paul -Green, Rafael Garcia-Suarez, Rainer Tammer, Ricardo Signes, Steffen Mueller, -Zsbán Ambrus, Ævar Arnfjörð Bjarmason +Craig A. Berry, David Golden, Father Chrysostomos, Florian Ragwitz, H.Merijn +Brand, Karl Williamson, Nicholas Clark, Pau Amma and Ricardo Signes. =head1 Reporting Bugs @@ -86,7 +212,7 @@ recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://rt.perl.org/perlbug/ . There may also be information at http://www.perl.org/ , the Perl Home Page. -If you believe you have an unreported bug, please run the B<perlbug> +If you believe you have an unreported bug, please run the L<perlbug> program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of C<perl -V>, will be sent off to perlbug@perl.org to be diff --git a/Master/tlpkg/tlperl/lib/pods/perldgux.pod b/Master/tlpkg/tlperl/lib/pods/perldgux.pod index 8e2cbf15cd3..fd6eaa3baa1 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldgux.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldgux.pod @@ -102,7 +102,7 @@ Run the command "make install" =head1 AUTHOR Takis Psarogiannakopoulos -Universirty of Cambridge +University of Cambridge Centre for Mathematical Sciences Department of Pure Mathematics Wilberforce road diff --git a/Master/tlpkg/tlperl/lib/pods/perldiag.pod b/Master/tlpkg/tlperl/lib/pods/perldiag.pod index 5d0f503ef36..8f2ad2913f2 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldiag.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldiag.pod @@ -50,7 +50,7 @@ letter. to check the return value of your socket() call? See L<perlfunc/accept>. -=item Allocation too large: %lx +=item Allocation too large: %x (X) You can't allocate more than 64K on an MS-DOS machine. @@ -89,6 +89,64 @@ C<tr/a-y//>, which was probably not what you would have expected.) you thought. Normally it's pretty easy to disambiguate it by supplying a missing quote, operator, parenthesis pair or declaration. +=item Ambiguous use of %c resolved as operator %c + +(W ambiguous) C<%>, C<&>, and C<*> are both infix operators (modulus, +bitwise and, and multiplication) I<and> initial special characters +(denoting hashes, subroutines and typeglobs), and you said something +like C<*foo * foo> that might be interpreted as either of them. We +assumed you meant the infix operator, but please try to make it more +clear -- in the example given, you might write C<*foo * foo()> if you +really meant to multiply a glob by the result of calling a function. + +=item Ambiguous use of %c{%s} resolved to %c%s + +(W ambiguous) You wrote something like C<@{foo}>, which might be +asking for the variable C<@foo>, or it might be calling a function +named foo, and dereferencing it as an array reference. If you wanted +the varable, you can just write C<@foo>. If you wanted to call the +function, write C<@{foo()}> ... or you could just not have a variable +and a function with the same name, and save yourself a lot of trouble. + +=item Ambiguous use of %c{%s[...]} resolved to %c%s[...] + +=item Ambiguous use of %c{%s{...}} resolved to %c%s{...} + +(W ambiguous) You wrote something like C<${foo[2]}> (where foo +represents the name of a Perl keyword), which might be looking for +element number 2 of the array named C<@foo>, in which case please write +C<$foo[2]>, or you might have meant to pass an anonymous arrayref to +the function named foo, and then do a scalar deref on the value it +returns. If you meant that, write C<${foo([2])}>. + +In regular expressions, the C<${foo[2]}> syntax is sometimes necessary +to disambiguate between array subscripts and character classes. +C</$length[2345]/>, for instance, will be interpreted as C<$length> +followed by the character class C<[2345]>. If an array subscript is what +you want, you can avoid the warning by changing C</${length[2345]}/> +to the unsightly C</${\$length[2345]}/>, by renaming your array to +something that does not coincide with a built-in keyword, or by +simply turning off warnings with C<no warnings 'ambiguous';>. + +=item Ambiguous use of -%s resolved as -&%s() + +(W ambiguous) You wrote something like C<-foo>, which might be the +string C<"-foo">, or a call to the function C<foo>, negated. If you meant +the string, just write C<"-foo">. If you meant the function call, +write C<-foo()>. + +=item Ambiguous use of 's//le...' resolved as 's// le...'; Rewrite as 's//el' if you meant 'use locale rules and evaluate rhs as an expression'. In Perl 5.16, it will be resolved the other way + +(W deprecated, ambiguous) You wrote a pattern match with substitution +immediately followed by "le". In Perl 5.14 and earlier, this is +resolved as meaning to take the result of the substitution, and see if +it is stringwise less-than-or-equal-to what follows in the expression. +Having the "le" immediately following a pattern is deprecated behavior, +so in Perl 5.16, this expression will be resolved as meaning to do the +pattern match using the rules of the current locale, and evaluate the +rhs as an expression when doing the substitution. In 5.14, if you want +the latter interpretation, you can simply write "el" instead. + =item '|' and '<' may not both be specified on command line (F) An error peculiar to VMS. Perl does its own command line @@ -120,13 +178,6 @@ hash) and then work on that scalar value. This is probably not what you meant to do. See L<perlfunc/grep> and L<perlfunc/map> for alternatives. -=item Args must match #! line - -(F) The setuid emulator requires that the arguments Perl was invoked -with match the arguments specified on the #! line. Since some systems -impose a one-argument limit on the #! line, try combining switches; -for example, turn C<-w -U> into C<-wU>. - =item Arg too short for msgsnd (F) msgsnd() requires a string at least as long as sizeof(long). @@ -197,8 +248,8 @@ know which context to supply to the right side. (W threads)(S) When using threaded Perl, a thread (not necessarily the main thread) exited while there were still other threads running. -Usually it's a good idea to first collect the return values of the -created threads by joining them, and only then exit from the main +Usually it's a good idea first to collect the return values of the +created threads by joining them, and only then to exit from the main thread. See L<threads>. =item Attempt to access disallowed key '%s' in a restricted hash @@ -234,7 +285,7 @@ which is not in its key set. (F) The failing code attempted to delete a key whose value has been declared readonly from a restricted hash. -=item Attempt to free non-arena SV: 0x%lx +=item Attempt to free non-arena SV: 0x%x (P internal) All SV objects are supposed to be allocated from arenas that will be garbage collected on exit. An SV was discovered to be @@ -242,7 +293,7 @@ outside any of those arenas. =item Attempt to free nonexistent shared string -(P internal) Perl maintains a reference counted internal table of +(P internal) Perl maintains a reference-counted internal table of strings to optimize the storage and access of hash keys and other strings. This indicates someone tried to decrement the reference count of a string that can no longer be found in the table. @@ -308,19 +359,19 @@ dereference it first. See L<perlfunc/substr>. =item Attribute "locked" is deprecated -(D deprecated) You have used the attributes pragam to modify the "locked" +(D deprecated) You have used the attributes pragma to modify the "locked" attribute on a code reference. The :locked attribute is obsolete, has had no -effect since 5005 threads were removed, and will be removed in the next major +effect since 5005 threads were removed, and will be removed in a future release of Perl 5. =item Attribute "unique" is deprecated -(D deprecated) You have used the attributes pragam to modify the "unique" +(D deprecated) You have used the attributes pragma to modify the "unique" attribute on an array, hash or scalar reference. The :unique attribute has -had no effect since Perl 5.8.8, and will be removed in the next major -release of Perl 5. +had no effect since Perl 5.8.8, and will be removed in a future release +of Perl 5. -=item Bad arg length for %s, is %d, should be %d +=item Bad arg length for %s, is %u, should be %d (F) You passed a buffer of the wrong size to one of msgctl(), semctl() or shmctl(). In C parlance, the correct sizes are, respectively, @@ -382,7 +433,7 @@ plugin API. (S malloc) An internal routine called realloc() on something that had never been malloc()ed in the first place. Mandatory, but can be disabled -by setting environment variable C<PERL_BADFREE> to 1. +by setting the environment variable C<PERL_BADFREE> to 1. =item Bad symbol for array @@ -469,7 +520,15 @@ check the return value of your socket() call? See L<perlfunc/bind>. =item binmode() on closed filehandle %s (W unopened) You tried binmode() on a filehandle that was never opened. -Check you control flow and number of arguments. +Check your control flow and number of arguments. + +=item "\b{" is deprecated; use "\b\{" instead + +=item "\B{" is deprecated; use "\B\{" instead + +(W deprecated, regexp) Use of an unescaped "{" immediately following a +C<\b> or C<\B> is now deprecated so as to reserve its use for Perl +itself in a future release. =item Bit vector size > 32 non-portable @@ -478,7 +537,7 @@ Check you control flow and number of arguments. =item Bizarre copy of %s in %s (P) Perl detected an attempt to copy an internal value that is not -copyable. +copiable. =item Buffer overflow in prime_env_iter: %s @@ -524,7 +583,7 @@ from that type of reference to a typeglob. =item Cannot copy to %s in %s (P) Perl detected an attempt to copy a value to an internal type that cannot -be directly assigned not. +be directly assigned to. =item Cannot find encoding "%s" @@ -551,12 +610,6 @@ a C<given> block. You probably meant to use C<next> or C<last>. (F) You called C<break>, but you're not inside a C<given> block. -=item Can't call method "%s" in empty package "%s" - -(F) You called a method correctly, and it correctly indicated a package -functioning as a class, but that package doesn't have ANYTHING defined -in it, let alone methods. See L<perlobj>. - =item Can't call method "%s" on an undefined value (F) You used the syntax of a method call, but the slot filled by the @@ -595,13 +648,7 @@ that you can chdir to, possibly because it doesn't exist. (P) For some reason you can't check the filesystem of the script for nosuid. -=item Can't coerce array into hash - -(F) You used an array where a hash was expected, but the array has no -information on how to map from keys to array indices. You can do that -only with arrays that have a hash reference at index 0. - -=item Can't coerce %s to integer in %s +=item Can't coerce %s to %s in %s (F) Certain types of SVs, in particular real symbol table entries (typeglobs), can't be forced to stop being what they are. So you can't @@ -616,16 +663,6 @@ You CAN say but then $foo no longer contains a glob. -=item Can't coerce %s to number in %s - -(F) Certain types of SVs, in particular real symbol table entries -(typeglobs), can't be forced to stop being what they are. - -=item Can't coerce %s to string in %s - -(F) Certain types of SVs, in particular real symbol table entries -(typeglobs), can't be forced to stop being what they are. - =item Can't "continue" outside a when block (F) You called C<continue>, but you're not inside a C<when> @@ -636,12 +673,6 @@ or C<default> block. (P) An error peculiar to VMS. The process is suffering from exhausted quotas or other plumbing problems. -=item Can't declare class for non-scalar %s in "%s" - -(F) Currently, only scalar variables can be declared with a specific -class qualifier in a "my", "our" or "state" declaration. The semantics may be -extended for other types of variables in future. - =item Can't declare %s in "%s" (F) Only scalar, array, and hash variables may be declared as "my", "our" or @@ -750,20 +781,22 @@ nesting levels, the following is missing its final parenthesis: print q(The character '(' starts a side comment.); -If you're getting this error from a here-document, you may have included -unseen whitespace before or after your closing tag. A good programmer's -editor will have a way to help you find these characters. +If you're getting this error from a here-document, you may have +included unseen whitespace before or after your closing tag or there +may not be a linebreak after it. A good programmer's editor will have +a way to help you find these characters (or lack of characters). See +L<perlop> for the full details on here-documents. =item Can't find Unicode property definition "%s" -(F) You may have tried to use C<\p> which means a Unicode property (for -example C<\p{Lu}> matches all uppercase letters). If you did mean to use a -Unicode property, see +(F) You may have tried to use C<\p> which means a Unicode +property (for example C<\p{Lu}> matches all uppercase +letters). If you did mean to use a Unicode property, see L<perluniprops/Properties accessible through \p{} and \P{}> -for a complete list of available properties. -If you didn't mean to use a Unicode property, escape the C<\p>, either -by C<\\p> (just the C<\p>) or by C<\Q\p> (the rest of the string, until -possible C<\E>). +for a complete list of available properties. If you didn't +mean to use a Unicode property, escape the C<\p>, either by C<\\p> +(just the C<\p>) or by C<\Q\p> (the rest of the string, or +until C<\E>). =item Can't fork: %s @@ -783,12 +816,12 @@ Under VMS, access checks are done by filename, rather than by bits in the stat buffer, so that ACLs and other protections can be taken into account. Unfortunately, Perl assumes that the stat buffer contains all the necessary information, and passes it, instead of the filespec, to -the access checking routine. It will try to retrieve the filespec using +the access-checking routine. It will try to retrieve the filespec using the device name and FID present in the stat buffer, but this works only if you haven't made a subsequent call to the CRTL stat() routine, because the device name is overwritten with each call. If this warning -appears, the name lookup failed, and the access checking routine gave up -and returned FALSE, just to be conservative. (Note: The access checking +appears, the name lookup failed, and the access-checking routine gave up +and returned FALSE, just to be conservative. (Note: The access-checking routine knows about the Perl C<stat> operator and file tests, so you shouldn't ever see this warning in response to a Perl command; it arises only if some internal code takes stat buffers lightly.) @@ -944,7 +977,7 @@ a NULL. =item Can't modify non-lvalue subroutine call (F) Subroutines meant to be used in lvalue context should be declared as -such, see L<perlsub/"Lvalue subroutines">. +such. See L<perlsub/"Lvalue subroutines">. =item Can't msgrcv to read-only var @@ -971,7 +1004,7 @@ the command line. =item Can't open a reference (W io) You tried to open a scalar reference for reading or writing, -using the 3-arg open() syntax : +using the 3-arg open() syntax: open FH, '>', $ref; @@ -1054,7 +1087,7 @@ to reopen it to accept binary data. Alas, it failed. (F|P) Error resolving overloading specified by a method name (as opposed to a subroutine reference): no such method callable via the package. If -method name is C<???>, this is an internal error. +the method name is C<???>, this is an internal error. =item Can't return %s from lvalue subroutine @@ -1099,11 +1132,6 @@ with Perl, though, if you really want to do that. however, redefine it while it's running, and you can even undef the redefined subroutine while the old routine is running. Go figure. -=item Can't unshift - -(F) You tried to unshift an "unreal" array that can't be unshifted, such -as the main Perl stack. - =item Can't upgrade %s (%d) to %d (P) The internal sv_upgrade routine adds "members" to an SV, making it @@ -1211,6 +1239,15 @@ references can be weakened. with an assignment operator, which implies modifying the value itself. Perhaps you need to copy the value to a temporary, and repeat that. +=item Character following "\c" must be ASCII + +(F|W deprecated, syntax) In C<\cI<X>>, I<X> must be an ASCII character. +It is planned to make this fatal in all instances in Perl 5.16. In the +cases where it isn't fatal, the character this evaluates to is +derived by exclusive or'ing the code point of this character with 0x40. + +Note that non-alphabetic ASCII characters are discouraged here as well. + =item Character in 'C' format wrapped in pack (W pack) You said @@ -1289,6 +1326,21 @@ uses the character values modulus 256 instead, as if you had provided: unpack("s", "\x{f3}b") +=item "\c{" is deprecated and is more clearly written as ";" + +(D deprecated, syntax) The C<\cI<X>> construct is intended to be a way +to specify non-printable characters. You used it with a "{" which +evaluates to ";", which is printable. It is planned to remove the +ability to specify a semi-colon this way in Perl 5.16. Just use a +semi-colon or a backslash-semi-colon without the "\c". + +=item "\c%c" is more clearly written simply as "%s" + +(W syntax) The C<\cI<X>> construct is intended to be a way to specify +non-printable characters. You used it for a printable one, which is better +written as simply itself, perhaps preceded by a backslash for non-word +characters. + =item close() on unopened filehandle %s (W unopened) You tried to close a filehandle that was never opened. @@ -1298,11 +1350,41 @@ uses the character values modulus 256 instead, as if you had provided: (W io) The dirhandle you tried to close is either closed or not really a dirhandle. Check your control flow. +=item Closure prototype called + +(F) If a closure has attributes, the subroutine passed to an attribute +handler is the prototype that is cloned when a new closure is created. +This subroutine cannot be called. + =item Code missing after '/' (F) You had a (sub-)template that ends with a '/'. There must be another template code following the slash. See L<perlfunc/pack>. +=item Code point 0x%X is not Unicode, may not be portable + +=item Code point 0x%X is not Unicode, no properties match it; all inverse properties do + +(W utf8, non_unicode) You had a code point above the Unicode maximum of U+10FFFF. + +Perl allows strings to contain a superset of Unicode code +points, up to the limit of what is storable in an unsigned integer on +your system, but these may not be accepted by other languages/systems. +At one time, it was legal in some standards to have code points up to +0x7FFF_FFFF, but not higher. Code points above 0xFFFF_FFFF require +larger than a 32 bit word. + +None of the Unicode or Perl-defined properties will match a non-Unicode +code point. For example, + + chr(0x7FF_FFFF) =~ /\p{Any}/ + +will not match, because the code point is not in Unicode. But + + chr(0x7FF_FFFF) =~ /\P{Any}/ + +will match. + =item %s: Command not found (A) You've accidentally run your script through B<csh> instead of Perl. @@ -1330,10 +1412,10 @@ on I<Mastering Regular Expressions>.) (W threads) Within a thread-enabled program, you tried to call cond_broadcast() on a variable which wasn't locked. The cond_broadcast() -function is used to wake up another thread that is waiting in a +function is used to wake up another thread that is waiting in a cond_wait(). To ensure that the signal isn't sent before the other thread -has a chance to enter the wait, it is usual for the signaling thread to -first wait for a lock on variable. This lock attempt will only succeed +has a chance to enter the wait, it is usual for the signaling thread +first to wait for a lock on variable. This lock attempt will only succeed after the other thread has entered cond_wait() and thus relinquished the lock. @@ -1341,10 +1423,10 @@ lock. (W threads) Within a thread-enabled program, you tried to call cond_signal() on a variable which wasn't locked. The cond_signal() -function is used to wake up another thread that is waiting in a +function is used to wake up another thread that is waiting in a cond_wait(). To ensure that the signal isn't sent before the other thread -has a chance to enter the wait, it is usual for the signaling thread to -first wait for a lock on variable. This lock attempt will only succeed +has a chance to enter the wait, it is usual for the signaling thread +first to wait for a lock on variable. This lock attempt will only succeed after the other thread has entered cond_wait() and thus relinquished the lock. @@ -1409,7 +1491,7 @@ expression compiler gave it. (P) The regular expression engine got passed a regexp program without a valid magic number. -=item Corrupt malloc ptr 0x%lx at 0x%lx +=item Corrupt malloc ptr 0x%x at 0x%x (P) The malloc package that comes with Perl had an internal failure. @@ -1441,6 +1523,15 @@ array is empty, just use C<if (@array) { # not empty }> for example. checks for an undefined I<scalar> value. If you want to see if the hash is empty, just use C<if (%hash) { # not empty }> for example. +=item (?(DEFINE)....) does not allow branches in regex; marked by <-- HERE in m/%s/ + +(F) You used something like C<(?(DEFINE)...|..)> which is illegal. The +most likely cause of this error is that you left out a parenthesis inside +of the C<....> part. + +The <-- HERE shows in the regular expression about where the problem was +discovered. + =item %s defines neither package nor VERSION--version check failed (F) You said something like "use Module 42" but in the Module file @@ -1452,13 +1543,13 @@ there are neither package declarations nor a C<$VERSION>. long for Perl to handle. You have to be seriously twisted to write code that triggers this error. -=item Deprecated character(s) in \\N{...} starting at '%s' +=item Deprecated character in \N{...}; marked by <-- HERE in \N{%s<-- HERE %s (D deprecated) Just about anything is legal for the C<...> in C<\N{...}>. -But starting in 5.12, non-reasonable ones that don't look like names are -deprecated. A reasonable name begins with an alphabetic character and -continues with any combination of alphanumerics, dashes, spaces, parentheses or -colons. +But starting in 5.12, non-reasonable ones that don't look like names +are deprecated. A reasonable name begins with an alphabetic character +and continues with any combination of alphanumerics, dashes, spaces, +parentheses or colons. =item Deprecated use of my() in false conditional @@ -1500,8 +1591,8 @@ do. See L<perlfunc/require>. =item (Did you mean &%s instead?) -(W) You probably referred to an imported subroutine &FOO as $FOO or some -such. +(W misc) You probably referred to an imported subroutine &FOO as $FOO or +some such. =item (Did you mean "local" instead of "our"?) @@ -1518,7 +1609,7 @@ carried away. =item Died (F) You passed die() an empty string (the equivalent of C<die "">) or -you called it with no args and both C<$@> and C<$_> were empty. +you called it with no args and C<$@> was empty. =item Document contains no data @@ -1614,10 +1705,11 @@ is unsafe. See L<perlre/(?{ code })>, and L<perlsec>. (F) Perl tried to compile a regular expression containing the C<(?{ ... })> zero-width assertion at run time, as it would when the -pattern contains interpolated values. Since that is a security risk, it -is not allowed. If you insist, you may still do this by explicitly -building the pattern from an interpolated string at run time and using -that in an eval(). See L<perlre/(?{ code })>. +pattern contains interpolated values. Since that is a security risk, +it is not allowed. If you insist, you may still do this by using the +C<re 'eval'> pragma or by explicitly building the pattern from an +interpolated string at run time and using that in an eval(). See +L<perlre/(?{ code })>. =item %s: Eval-group not allowed, use re 'eval' @@ -1642,7 +1734,8 @@ variable and glob that. =item exec? I'm not *that* kind of operating system -(F) The C<exec> function is not implemented in MacPerl. See L<perlport>. +(F) The C<exec> function is not implemented on some systems, e.g., Symbian +OS. See L<perlport>. =item Execution of %s aborted due to compilation errors. @@ -1700,7 +1793,7 @@ in your false range is interpreted as a literal "-". Consider quoting the "-", "\-". The <-- HERE shows in the regular expression about where the problem was discovered. See L<perlre>. -=item Fatal VMS error at %s, line %d +=item Fatal VMS error (status=%d) at %s, line %d (P) An error peculiar to VMS. Something untoward happened in a VMS system service or RTL routine; Perl's exit status should provide more @@ -1722,7 +1815,7 @@ is not possible. (W pack) Each line in an uuencoded string start with a length indicator which can't encode values above 63. So there is no point in asking for a line length bigger than that. Perl will behave as if you specified -C<u63> as format. +C<u63> as the format. =item Filehandle %s opened only for input @@ -1735,10 +1828,10 @@ write the file, use ">" or ">>". See L<perlfunc/open>. (W io) You tried to read from a filehandle opened only for writing, If you intended it to be a read/write filehandle, you needed to open it -with "+<" or "+>" or "+>>" instead of with "<" or nothing. If you -intended only to read from the file, use "<". See L<perlfunc/open>. -Another possibility is that you attempted to open filedescriptor 0 -(also known as STDIN) for output (maybe you closed STDIN earlier?). +with "+<" or "+>" or "+>>" instead of with ">". If you intended only to +read from the file, use "<". See L<perlfunc/open>. Another possibility +is that you attempted to open filedescriptor 0 (also known as STDIN) for +output (maybe you closed STDIN earlier?). =item Filehandle %s reopened as %s only for input @@ -1852,16 +1945,16 @@ a term, so it's looking for the corresponding right angle bracket, and not finding it. Chances are you left some needed parentheses out earlier in the line, and you really meant a "less than". -=item gmtime(%.0f) too large +=item gmtime(%f) too large -(W overflow) You called C<gmtime> with an number that was larger than +(W overflow) You called C<gmtime> with a number that was larger than it can reliably handle and C<gmtime> probably returned the wrong date. This warning is also triggered with nan (the special not-a-number value). -=item gmtime(%.0f) too small +=item gmtime(%f) too small -(W overflow) You called C<gmtime> with an number that was smaller than +(W overflow) You called C<gmtime> with a number that was smaller than it can reliably handle and C<gmtime> probably returned the wrong date. This warning is also triggered with nan (the special not-a-number value). @@ -1878,9 +1971,8 @@ unspecified destination. See L<perlfunc/goto>. =item ()-group starts with a count -(F) A ()-group started with a count. A count is -supposed to follow something: a template character or a ()-group. - See L<perlfunc/pack>. +(F) A ()-group started with a count. A count is supposed to follow +something: a template character or a ()-group. See L<perlfunc/pack>. =item %s had compilation errors. @@ -1902,6 +1994,26 @@ spots. This is now heavily deprecated. (F) The parser has given up trying to parse the program after 10 errors. Further error messages would likely be uninformative. +=item Having no space between pattern and following word is deprecated + +(D syntax) + +You had a word that isn't a regex modifier immediately following a +pattern without an intervening space. If you are trying to use the C</le> +flags on a substitution, use C</el> instead. Otherwise, add white space +between the pattern and following word to eliminate the warning. As an +example of the latter, the two constructs: + + $a =~ m/$foo/sand $bar + $a =~ m/$foo/s and $bar + +both currently mean the same thing, but it is planned to disallow the first +form in Perl 5.16. And, + + $a =~ m/$foo/and $bar + +will be disallowed too. + =item Hexadecimal number > 0xffffffff non-portable (W portable) The hexadecimal number you specified is larger than 2**32-1 @@ -1932,7 +2044,7 @@ been used, and the correct charname handler is in scope. binary number. Interpretation of the binary number stopped before the offending digit. -=item Illegal character %s (carriage return) +=item Illegal character \%o (carriage return) (F) Perl normally treats carriage returns in the program text as it would any other whitespace, which means you should never see this error @@ -1943,7 +2055,7 @@ to your Perl administrator. =item Illegal character in prototype for %s : %s (W illegalproto) An illegal character was found in a prototype declaration. -Legal characters in prototypes are $, @, %, *, ;, [, ], &, and \. +Legal characters in prototypes are $, @, %, *, ;, [, ], &, \, and +. =item Illegal declaration of anonymous subroutine @@ -2067,6 +2179,20 @@ C<$ENV{ENV}>, C<$ENV{BASH_ENV}> or C<$ENV{TERM}> are derived from data supplied (or potentially supplied) by the user. The script must set the path to a known value, using trustworthy data. See L<perlsec>. +=item Insecure user-defined property %s + +(F) Perl detected tainted data when trying to compile a regular +expression that contains a call to a user-defined character property +function, i.e. C<\p{IsFoo}> or C<\p{InFoo}>. +See L<perlunicode/User-Defined Character Properties> and L<perlsec>. + + +=item Integer overflow in format string for %s + +(F) The indexes and widths specified in the format string of C<printf()> +or C<sprintf()> are too large. The numbers must not overflow the size of +integers for your architecture. + =item Integer overflow in %s number (W overflow) The hexadecimal, octal or binary number you have specified @@ -2079,12 +2205,6 @@ transparently promotes all numbers to a floating point representation internally--subject to loss of precision errors in subsequent operations. -=item Integer overflow in format string for %s - -(F) The indexes and widths specified in the format string of C<printf()> -or C<sprintf()> are too large. The numbers must not overflow the size of -integers for your architecture. - =item Integer overflow in version (F) Some portion of a version initialization is too large for the @@ -2124,12 +2244,12 @@ L<perlop/Terms and List Operators (Leftward)>. =item Invalid %s attribute: %s -The indicated attribute for a subroutine or variable was not recognized +(F) The indicated attribute for a subroutine or variable was not recognized by Perl or by a user-supplied handler. See L<attributes>. =item Invalid %s attributes: %s -The indicated attributes for a subroutine or variable were not +(F) The indicated attributes for a subroutine or variable were not recognized by Perl or by a user-supplied handler. See L<attributes>. =item Invalid conversion in %s: "%s" @@ -2146,11 +2266,18 @@ The escape was replaced with REPLACEMENT CHARACTER (U+FFFD) instead. The <-- HERE shows in the regular expression about where the escape was discovered. +=item Invalid hexadecimal number in \N{U+...} + +(F) The character constant represented by C<...> is not a valid hexadecimal +number. Either it is empty, or you tried to use a character other than +0 - 9 or A - F, a - f in a hexadecimal number. + =item Invalid mro name: '%s' -(F) You tried to C<mro::set_mro("classname", "foo")> -or C<use mro 'foo'>, where C<foo> is not a valid method resolution order (MRO). -(Currently, the only valid ones are C<dfs> and C<c3>). See L<mro>. +(F) You tried to C<mro::set_mro("classname", "foo")> or C<use mro 'foo'>, +where C<foo> is not a valid method resolution order (MRO). Currently, +the only valid ones supported are C<dfs> and C<c3>, unless you have loaded +a module that is a MRO plugin. See L<mro> and L<perlmroapi>. =item Invalid [] range "%s" in regex; marked by <-- HERE in m/%s/ @@ -2174,11 +2301,20 @@ See L<attributes>. =item Invalid separator character %s in PerlIO layer specification %s -(W layer) When pushing layers onto the Perl I/O system, something other than a -colon or whitespace was seen between the elements of a layer list. +(W layer) When pushing layers onto the Perl I/O system, something other +than a colon or whitespace was seen between the elements of a layer list. If the previous attribute had a parenthesised parameter list, perhaps that list was terminated too soon. +=item Invalid strict version format (%s) + +(F) A version number did not meet the "strict" criteria for versions. +A "strict" version number is a positive decimal number (integer or +decimal-fraction) without exponentiation or else a dotted-decimal +v-string with a leading 'v' character and at least three components. +The parenthesized text indicates which criteria were not met. +See the L<version> module for more details on allowed version formats. + =item Invalid type '%s' in %s (F) The given character is not a valid pack or unpack type. @@ -2186,16 +2322,24 @@ See L<perlfunc/pack>. (W) The given character is not a valid pack or unpack type but used to be silently ignored. -=item Invalid version format (multiple underscores) +=item Invalid version format (%s) -(F) Versions may contain at most a single underscore, which signals -that the version is a beta release. See L<version> for the allowed -version formats. +(F) A version number did not meet the "lax" criteria for versions. +A "lax" version number is a positive decimal number (integer or +decimal-fraction) without exponentiation or else a dotted-decimal +v-string. If the v-string has fewer than three components, it must +have a leading 'v' character. Otherwise, the leading 'v' is optional. +Both decimal and dotted-decimal versions may have a trailing "alpha" +component separated by an underscore character after a fractional or +dotted-decimal component. The parenthesized text indicates which +criteria were not met. See the L<version> module for more details on +allowed version formats. -=item Invalid version format (underscores before decimal) +=item Invalid version object -(F) Versions may not contain decimals after the optional underscore. -See L<version> for the allowed version formats. +(F) The internal structure of the version object was invalid. Perhaps +the internals were modified directly in some way or an arbitrary reference +was blessed into the "version" class. =item ioctl is not implemented @@ -2205,34 +2349,36 @@ strange for a machine that supports C. =item ioctl() on unopened %s (W unopened) You tried ioctl() on a filehandle that was never opened. -Check you control flow and number of arguments. +Check your control flow and number of arguments. =item IO layers (like '%s') unavailable (F) Your Perl has not been configured to have PerlIO, and therefore -you cannot use IO layers. To have PerlIO Perl must be configured +you cannot use IO layers. To have PerlIO, Perl must be configured with 'useperlio'. =item IO::Socket::atmark not implemented on this architecture (F) Your machine doesn't implement the sockatmark() functionality, -neither as a system call or an ioctl call (SIOCATMARK). +neither as a system call nor an ioctl call (SIOCATMARK). =item $* is no longer supported -(D deprecated, syntax) The special variable C<$*>, deprecated in older perls, has -been removed as of 5.9.0 and is no longer supported. In previous versions of perl the use of -C<$*> enabled or disabled multi-line matching within a string. +(D deprecated, syntax) The special variable C<$*>, deprecated in older +perls, has been removed as of 5.9.0 and is no longer supported. In +previous versions of perl the use of C<$*> enabled or disabled multi-line +matching within a string. Instead of using C<$*> you should use the C</m> (and maybe C</s>) regexp -modifiers. (In older versions: when C<$*> was set to a true value then all regular -expressions behaved as if they were written using C</m>.) +modifiers. You can enable C</m> for a lexical scope (even a whole file) +with C<use re '/m'>. (In older versions: when C<$*> was set to a true value +then all regular expressions behaved as if they were written using C</m>.) =item $# is no longer supported -(D deprecated, syntax) The special variable C<$#>, deprecated in older perls, has -been removed as of 5.9.3 and is no longer supported. You should use the -printf/sprintf functions instead. +(D deprecated, syntax) The special variable C<$#>, deprecated in older +perls, has been removed as of 5.9.3 and is no longer supported. You +should use the printf/sprintf functions instead. =item `%s' is not a code reference @@ -2281,11 +2427,10 @@ an undefined value for the length. See L<perlfunc/pack>. =item Lexing code attempted to stuff non-Latin-1 character into Latin-1 input (F) An extension is attempting to insert text into the current parse -(using L<lex_stuff_pvn_flags|perlapi/lex_stuff_pvn_flags> or similar), but -tried to insert a character that couldn't be part of the current input. -This is an inherent pitfall of the stuffing mechanism, and one of the -reasons to avoid it. Where it is necessary to stuff, stuffing only -plain ASCII is recommended. +(using L<lex_stuff_pvn|perlapi/lex_stuff_pvn> or similar), but tried to insert a character +that couldn't be part of the current input. This is an inherent pitfall +of the stuffing mechanism, and one of the reasons to avoid it. Where it +is necessary to stuff, stuffing only plain ASCII is recommended. =item Lexing code internal error (%s) @@ -2298,16 +2443,16 @@ detectable way. to check the return value of your socket() call? See L<perlfunc/listen>. -=item localtime(%.0f) too large +=item localtime(%f) too large -(W overflow) You called C<localtime> with an number that was larger +(W overflow) You called C<localtime> with a number that was larger than it can reliably handle and C<localtime> probably returned the wrong date. This warning is also triggered with nan (the special not-a-number value). -=item localtime(%.0f) too small +=item localtime(%f) too small -(W overflow) You called C<localtime> with an number that was smaller +(W overflow) You called C<localtime> with a number that was smaller than it can reliably handle and C<localtime> probably returned the wrong date. This warning is also triggered with nan (the special not-a-number value). @@ -2335,9 +2480,9 @@ instead on the filehandle.) =item lvalue attribute ignored after the subroutine has been defined (W misc) Making a subroutine an lvalue subroutine after it has been defined -by declaring the subroutine with a lvalue attribute is not -possible. To make the the subroutine a lvalue subroutine add the -lvalue attribute to the definition, or put the the declaration before +by declaring the subroutine with an lvalue attribute is not +possible. To make the subroutine an lvalue subroutine add the +lvalue attribute to the definition, or put the declaration before the definition. =item Lvalue subs returning %s not implemented yet @@ -2346,14 +2491,14 @@ the definition. values cannot be returned in subroutines used in lvalue context. See L<perlsub/"Lvalue subroutines">. -=item Malformed integer in [] in pack +=item Malformed integer in [] in pack -(F) Between the brackets enclosing a numeric repeat count only digits +(F) Between the brackets enclosing a numeric repeat count only digits are permitted. See L<perlfunc/pack>. =item Malformed integer in [] in unpack -(F) Between the brackets enclosing a numeric repeat count only digits +(F) Between the brackets enclosing a numeric repeat count only digits are permitted. See L<perlfunc/pack>. =item Malformed PERLLIB_PREFIX @@ -2393,37 +2538,29 @@ message. See also L<Encode/"Handling Malformed Data">. -=item Malformed UTF-16 surrogate - -(F) Perl thought it was reading UTF-16 encoded character data but while -doing it Perl met a malformed Unicode surrogate. - =item Malformed UTF-8 returned by \N (F) The charnames handler returned malformed UTF-8. -=item Malformed UTF-8 string in pack +=item Malformed UTF-8 string in '%c' format in unpack -(F) You tried to pack something that didn't comply with UTF-8 encoding +(F) You tried to unpack something that didn't comply with UTF-8 encoding rules and perl was unable to guess how to make more progress. -=item Malformed UTF-8 string in unpack +=item Malformed UTF-8 string in pack -(F) You tried to unpack something that didn't comply with UTF-8 encoding +(F) You tried to pack something that didn't comply with UTF-8 encoding rules and perl was unable to guess how to make more progress. -=item Malformed UTF-8 string in '%c' format in unpack +=item Malformed UTF-8 string in unpack (F) You tried to unpack something that didn't comply with UTF-8 encoding rules and perl was unable to guess how to make more progress. -=item Maximal count of pending signals (%d) exceeded +=item Malformed UTF-16 surrogate -(F) Perl aborted due to a too high number of signals pending. This -usually indicates that your operating system tried to deliver signals -too fast (with a very high priority), starving the perl process from -resources it would need to reach a point where it can process signals -safely. (See L<perlipc/"Deferred Signals (Safe Signals)">.) +(F) Perl thought it was reading UTF-16 encoded character data but while +doing it Perl met a malformed Unicode surrogate. =item %s matches null string many times in regex; marked by <-- HERE in m/%s/ @@ -2432,6 +2569,14 @@ regular expression engine didn't specifically check for that. The <-- HERE shows in the regular expression about where the problem was discovered. See L<perlre>. +=item Maximal count of pending signals (%u) exceeded + +(F) Perl aborted due to too high a number of signals pending. This +usually indicates that your operating system tried to deliver signals +too fast (with a very high priority), starving the perl process from +resources it would need to reach a point where it can process signals +safely. (See L<perlipc/"Deferred Signals (Safe Signals)">.) + =item "%s" may clash with future reserved word (W) This warning may be due to running a perl5 script through a perl4 @@ -2477,10 +2622,14 @@ immediately after the switch, without intervening spaces. =item Missing braces on \N{} (F) Wrong syntax of character name literal C<\N{charname}> within -double-quotish context. This can also happen when there is a space (or -comment) between the C<\N> and the C<{> in a regex with the C</x> modifier. -This modifier does not change the requirement that the brace immediately follow -the C<\N>. +double-quotish context. This can also happen when there is a space +(or comment) between the C<\N> and the C<{> in a regex with the C</x> modifier. +This modifier does not change the requirement that the brace immediately +follow the C<\N>. + +=item Missing braces on \o{} + +(F) A C<\o> must be followed immediately by a C<{> in double-quotish context. =item Missing comma after first argument to %s function @@ -2518,32 +2667,31 @@ can vary from one line to the next. (F) Missing right brace in C<\x{...}>, C<\p{...}>, C<\P{...}>, or C<\N{...}>. -=item Missing right brace on \\N{} or unescaped left brace after \\N +=item Missing right brace on \N{} or unescaped left brace after \N -(F) -C<\N> has two meanings. +(F) C<\N> has two meanings. -The traditional one has it followed by a name enclosed -in braces, meaning the character (or sequence of characters) given by that name. -Thus C<\N{ASTERISK}> is another way of writing C<*>, valid in both -double-quoted strings and regular expression patterns. In patterns, it doesn't -have the meaning an unescaped C<*> does. +The traditional one has it followed by a name enclosed in braces, +meaning the character (or sequence of characters) given by that +name. Thus C<\N{ASTERISK}> is another way of writing C<*>, valid in both +double-quoted strings and regular expression patterns. In patterns, +it doesn't have the meaning an unescaped C<*> does. -Starting in Perl 5.12.0, C<\N> also can have an additional meaning (only) in -patterns, namely to match a non-newline character. (This is short for -C<[^\n]>, and like C<.> but is not affected by the C</s> regex modifier.) +Starting in Perl 5.12.0, C<\N> also can have an additional meaning (only) +in patterns, namely to match a non-newline character. (This is short +for C<[^\n]>, and like C<.> but is not affected by the C</s> regex modifier.) -This can lead to some ambiguities. When C<\N> is not followed immediately by a -left brace, Perl assumes the C<[^\n]> meaning. Also, if -the braces form a valid quantifier such as C<\N{3}> or C<\N{5,}>, Perl assumes -that this means to match the given quantity of non-newlines (in these examples, -3; and 5 or more, respectively). In all other case, where there is a C<\N{> -and a matching C<}>, Perl assumes that a character name is desired. +This can lead to some ambiguities. When C<\N> is not followed immediately +by a left brace, Perl assumes the C<[^\n]> meaning. Also, if the braces +form a valid quantifier such as C<\N{3}> or C<\N{5,}>, Perl assumes that this +means to match the given quantity of non-newlines (in these examples, +3; and 5 or more, respectively). In all other case, where there is a +C<\N{> and a matching C<}>, Perl assumes that a character name is desired. -However, if there is no matching C<}>, Perl doesn't know if it was mistakenly -omitted, or if C<[^\n]{> was desired, and -raises this error. If you meant the former, add the right brace; if you meant -the latter, escape the brace with a backslash, like so: C<\N\{> +However, if there is no matching C<}>, Perl doesn't know if it was +mistakenly omitted, or if C<[^\n]{> was desired, and raises this error. +If you meant the former, add the right brace; if you meant the latter, +escape the brace with a backslash, like so: C<\N\{> =item Missing right curly or square bracket @@ -2624,23 +2772,37 @@ See L<perlfunc/pack>. (F) Lexically scoped subroutines are not yet implemented. Don't try that yet. -=item "%s" variable %s can't be in a package +=item "my" variable %s can't be in a package (F) Lexically scoped variables aren't in a package, so it doesn't make sense to try to declare one with a package qualifier on the front. Use local() if you want to localize a package variable. -=item \\N in a character class must be a named character: \\N{...} +=item Name "%s::%s" used only once: possible typo + +(W once) Typographical errors often show up as unique variable names. +If you had a good reason for having a unique name, then just mention it +again somehow to suppress the message. The C<our> declaration is +provided for this purpose. + +NOTE: This warning detects symbols that have been used only once so $c, @c, +%c, *c, &c, sub c{}, c(), and c (the filehandle or format) are considered +the same; if a program uses $c only once but also uses any of the others it +will not trigger this warning. + +=item \N in a character class must be a named character: \N{...} (F) The new (5.12) meaning of C<\N> as C<[^\n]> is not valid in a bracketed -character class, for the same reason that C<.> in a character class loses its -specialness: it matches almost everything, which is probably not what you want. +character class, for the same reason that C<.> in a character class loses +its specialness: it matches almost everything, which is probably not +what you want. -=item \\N{NAME} must be resolved by the lexer +=item \N{NAME} must be resolved by the lexer -(F) When compiling a regex pattern, an unresolved named character or sequence -was encountered. This can happen in any of several ways that bypass the lexer, -such as using single-quotish context, or an extra backslash in double quotish: +(F) When compiling a regex pattern, an unresolved named character or +sequence was encountered. This can happen in any of several ways that +bypass the lexer, such as using single-quotish context, or an extra +backslash in double-quotish: $re = '\N{SPACE}'; # Wrong! $re = "\\N{SPACE}"; # Wrong! @@ -2666,24 +2828,6 @@ C<\N> is separated by spaces from the C<{>, in which case, remove the spaces. /\N {SPACE}/x; # Wrong! /\N{SPACE}/x; # ok -=item Name "%s::%s" used only once: possible typo - -(W once) Typographical errors often show up as unique variable names. -If you had a good reason for having a unique name, then just mention it -again somehow to suppress the message. The C<our> declaration is -provided for this purpose. - -NOTE: This warning detects symbols that have been used only once so $c, @c, -%c, *c, &c, sub c{}, c(), and c (the filehandle or format) are considered -the same; if a program uses $c only once but also uses any of the others it -will not trigger this warning. - -=item Invalid hexadecimal number in \\N{U+...} - -(F) The character constant represented by C<...> is not a valid hexadecimal -number. Either it is empty, or you tried to use a character other than 0 - 9 -or A - F, a - f in a hexadecimal number. - =item Negative '/' count in unpack (F) The length count obtained from a length/code unpack operation was @@ -2736,7 +2880,7 @@ One possible cause for this is that you expected to have imported a constant to your name space with B<use> or B<import> while no such importing took place, it may for example be that your operating system does not support that particular constant. Hopefully you did use an -explicit import list for the constants you expect to see, please see +explicit import list for the constants you expect to see; please see L<perlfunc/use> and L<perlfunc/import>. While an explicit import list would probably have caught this error earlier it naturally does not remedy the fact that your operating system still does not support that @@ -2753,7 +2897,7 @@ doesn't know where you want to pipe the output from this command. =item No DB::DB routine defined (F) The currently executing code was compiled with the B<-d> switch, but -for some reason the current debugger (e.g. F<perl5db.pl> or a C<Devel::> +for some reason the current debugger (e.g. F<perl5db.pl> or a C<Devel::> module) didn't define a routine to be called at the beginning of each statement. @@ -2769,10 +2913,6 @@ for some reason the current debugger (e.g. F<perl5db.pl> or a C<Devel::> module) didn't define a C<DB::sub> routine to be called at the beginning of each ordinary subroutine call. -=item No B<-e> allowed in setuid scripts - -(F) A setuid script can't be specified by the user. - =item No error file after 2> or 2>> on command line (F) An error peculiar to VMS. Perl handles its own command line @@ -2790,11 +2930,6 @@ matching counterpart. See L<perlfunc/pack>. redirection, and found a '<' on the command line, but can't find the name of the file from which to read data for stdin. -=item No #! line - -(F) The setuid emulator requires that scripts have a well-formed #! line -even on machines that don't support the #! construct. - =item No next::method '%s' found for %s (F) C<next::method> found no further instances of this method name @@ -2853,13 +2988,13 @@ package has restricted the set of allowed keys using the L<fields> pragma. =item No such class %s -(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. +(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 +(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 @@ -2904,11 +3039,11 @@ find out what kind of ref it really was. See L<perlref>. a reference to something else instead. You can use the ref() function to find out what kind of ref it really was. See L<perlref>. -=item Not a perl script +=item Not an unblessed ARRAY reference -(F) The setuid emulator requires that scripts have a well-formed #! line -even on machines that don't support the #! construct. The line must -mention perl. +(F) You passed a reference to a blessed array to C<push>, C<shift> or +another array function. These only accept unblessed array references +or arrays beginning explicitly with C<@>. =item Not a SCALAR reference @@ -2951,11 +3086,17 @@ to UTC. If it's not, define the logical name F<SYS$TIMEZONE_DIFFERENTIAL> to translate to the number of seconds which need to be added to UTC to get local time. +=item Non-octal character '%c'. Resolved as "%s" + +(W digit) In parsing an octal numeric constant, a character was +unexpectedly encountered that isn't octal. The resulting value is as +indicated. + =item Non-string passed as bitmask (W misc) A number has been passed as a bitmask argument to select(). Use the vec() function to construct the file descriptor bitmasks for -select. See L<perlfunc/select> +select. See L<perlfunc/select>. =item Null filename used @@ -2993,6 +3134,12 @@ versions of Perl are likely to eliminate this arbitrary limitation. In the meantime, try using scientific notation (e.g. "1e6" instead of "1_000_000"). +=item Number with no digits + +(F) Perl was looking for a number but found nothing that looked like +a number. This happens, for example with C<\o{}>, with no number between +the braces. + =item Octal number in vector unsupported (F) Numbers with a leading C<0> are not currently allowed in vectors. @@ -3005,8 +3152,6 @@ future version. (4294967295) and therefore non-portable between systems. See L<perlport> for more on portability concerns. -See also L<perlport> for writing portable code. - =item Odd number of arguments for overload::constant (W overload) The call to overload::constant contained an odd number of @@ -3024,7 +3169,7 @@ which is odd, because hashes come in key/value pairs. =item Offset outside string -(F, W layer) You tried to do a read/write/send/recv/seek operation +(F|W layer) You tried to do a read/write/send/recv/seek operation with an offset pointing outside the buffer. This is difficult to imagine. The sole exceptions to this are that zero padding will take place when going past the end of the string when either @@ -3053,14 +3198,14 @@ that isn't open. Check your control flow. See also L<perlfunc/-X>. =item Opening dirhandle %s also as a file -(W io deprecated) You used open() to associate a filehandle to +(W io, deprecated) You used open() to associate a filehandle to a symbol (glob or scalar) that already holds a dirhandle. Although legal, this idiom might render your code confusing and is deprecated. =item Opening filehandle %s also as a directory -(W io deprecated) You used opendir() to associate a dirhandle to +(W io, deprecated) You used opendir() to associate a dirhandle to a symbol (glob or scalar) that already holds a filehandle. Although legal, this idiom might render your code confusing and is deprecated. @@ -3070,7 +3215,35 @@ and is deprecated. (F) An attempt was made to perform an overloaded operation for which no handler was defined. While some handlers can be autogenerated in terms of other handlers, there is no default handler for any operation, unless -C<fallback> overloading key is specified to be true. See L<overload>. +the C<fallback> overloading key is specified to be true. See L<overload>. + +=item Operation "%s" returns its argument for non-Unicode code point 0x%X + +(W utf8, non_unicode) You performed an operation requiring Unicode +semantics on a code +point that is not in Unicode, so what it should do is not defined. Perl +has chosen to have it do nothing, and warn you. + +If the operation shown is "ToFold", it means that case-insensitive +matching in a regular expression was done on the code point. + +If you know what you are doing you can turn off this warning by +C<no warnings 'non_unicode';>. + +=item Operation "%s" returns its argument for UTF-16 surrogate U+%X + +(W utf8, surrogate) You performed an operation requiring Unicode +semantics on a Unicode +surrogate. Unicode frowns upon the use of surrogates for anything but +storing strings in UTF-16, but semantics are (reluctantly) defined for +the surrogates, and they are to do nothing for this operation. Because +the use of surrogates can be dangerous, Perl warns. + +If the operation shown is "ToFold", it means that case-insensitive +matching in a regular expression was done on the code point. + +If you know what you are doing you can turn off this warning by +C<no warnings 'surrogate';>. =item Operator or semicolon missing before %s @@ -3243,9 +3416,16 @@ failure was caught. (P) We popped the context stack to a context with the specified label, and then discovered it wasn't a context we know how to do a goto in. +=item panic: gp_free failed to free glob pointer + +(P) The internal routine used to clear a typeglob's entries tried +repeatedly, but each time something re-created entries in the glob. Most +likely the glob contains an object with a reference back to the glob and a +destructor that adds a new object to the glob. + =item panic: hfreeentries failed to free hash -(P) The internal routine used to clear a hashes entries tried repeatedly, +(P) The internal routine used to clear a hash's entries tried repeatedly, but each time something added more entries to the hash. Most likely the hash contains an object with a reference back to the hash and a destructor that adds a new object to the hash. @@ -3369,8 +3549,8 @@ was string. =item panic: unimplemented op %s (#%d) called -(P) The compiler is screwed up and attempted to use an op that isn't permitted -at run time. +(P) The compiler is screwed up and attempted to use an op that isn't +permitted at run time. =item panic: utf16_to_utf8: odd bytelen @@ -3386,6 +3566,11 @@ to even) byte length. (P) The lexer got into a bad state while processing a case modifier. +=item Parsing code internal error (%s) + +(F) Parsing code supplied by an extension violated the parser's API in +a detectable way. + =item Pattern subroutine nesting without pos change exceeded limit in regex; marked by <-- HERE in m/%s/ (F) You used a pattern that uses too many nested subpattern calls without @@ -3419,6 +3604,15 @@ redirected it with select().) "Can't locate object method \"%s\" via package \"%s\"". It often means that a method requires a package that has not been loaded. +=item Perl folding rules are not up-to-date for 0x%x; please use the perlbug utility to report + +(W regex, deprecated) You used a regular expression with +case-insensitive matching, and there is a bug in Perl in which the +built-in regular expression folding rules are not accurate. This may +lead to incorrect results. Please report this as a bug using the +"perlbug" utility. (This message is marked deprecated, so that it by +default will be turned-on.) + =item Perl_my_%s() not available (F) Your platform has very uncommon byte-order and integer size, @@ -3426,13 +3620,6 @@ so it was not possible to set up some or all fixed-width byte-order conversion functions. This is only a problem when you're using the '<' or '>' modifiers in (un)pack templates. See L<perlfunc/pack>. -=item Perl_pmflag() is deprecated, and will be removed from the XS API - -(D deprecated) XS code called the C function C<Perl_pmflag>. This was part of -Perl's listed public API for extending or embedding the perl interpreter. It has -now been removed from the public API, and will be removed in a future release, -hence XS code should be re-written not to use it. - =item Perl %s required--this is only version %s, stopped (F) The module in question uses features of a version of Perl more @@ -3465,9 +3652,9 @@ This error means that Perl detected that you and/or your operating system supplier and/or system administrator have set up the so-called locale system but Perl could not use those settings. This was not dead serious, fortunately: there is a "default locale" called "C" that -Perl can and will use, the script will be run. Before you really fix -the problem, however, you will get the same error message each time -you run Perl. How to really fix the problem can be found in +Perl can and will use, and the script will be run. Before you really +fix the problem, however, you will get the same error message each +time you run Perl. How to really fix the problem can be found in L<perllocale> section B<LOCALE PROBLEMS>. =item pid %x not a child @@ -3584,13 +3771,6 @@ higher precedence of C<==>. This is probably not what you want. (If you really meant to write this, disable the warning, or, better, put the parentheses explicitly and write C<$x & ($y == 0)>). -=item Possible unintended interpolation of %s in string - -(W ambiguous) You said something like `@foo' in a double-quoted string -but there was no array C<@foo> in scope at the time. If you wanted a -literal @foo, then write it as \@foo; otherwise find out what happened -to the array you apparently lost track of. - =item Possible unintended interpolation of $\ in regex (W ambiguous) You said something like C<m/$\/> in a regex. @@ -3605,6 +3785,13 @@ If instead you intended to match the word 'foo' at the end of the line followed by whitespace and the word 'bar' on the next line then you can use C<m/$(?)\/> (for example: C<m/foo$(?)\s+bar/>). +=item Possible unintended interpolation of %s in string + +(W ambiguous) You said something like `@foo' in a double-quoted string +but there was no array C<@foo> in scope at the time. If you wanted a +literal @foo, then write it as \@foo; otherwise find out what happened +to the array you apparently lost track of. + =item Precedence problem: open %s should be open(%s) (S precedence) The old irregular construct @@ -3657,6 +3844,30 @@ declared or defined with a different function prototype. (F) You've omitted the closing parenthesis in a function prototype definition. +=item \p{} uses Unicode rules, not locale rules + +(W) You compiled a regular expression that contained a Unicode property +match (C<\p> or C<\P>), but the regular expression is also being told to +use the run-time locale, not Unicode. Instead, use a POSIX character +class, which should know about the locale's rules. +(See L<perlrecharclass/POSIX Character Classes>.) + +Even if the run-time locale is ISO 8859-1 (Latin1), which is a subset of +Unicode, some properties will give results that are not valid for that +subset. + +Here are a couple of examples to help you see what's going on. If the +locale is ISO 8859-7, the character at code point 0xD7 is the "GREEK +CAPITAL LETTER CHI". But in Unicode that code point means the +"MULTIPLICATION SIGN" instead, and C<\p> always uses the Unicode +meaning. That means that C<\p{Alpha}> won't match, but C<[[:alpha:]]> +should. Only in the Latin1 locale are all the characters in the same +positions as they are in Unicode. But, even here, some properties give +incorrect results. An example is C<\p{Changes_When_Uppercased}> which +is true for "LATIN SMALL LETTER Y WITH DIAERESIS", but since the upper +case of that character is not in Latin1, in that locale it doesn't +change when upper cased. + =item Quantifier follows nothing in regex; marked by <-- HERE in m/%s/ (F) You started a regular expression with a quantifier. Backslash it if you @@ -3705,7 +3916,7 @@ before now. Check your control flow. (W unopened) You tried to read from a filehandle that was never opened. -=item Reallocation too large: %lx +=item Reallocation too large: %x (F) You can't allocate more than 64K on an MS-DOS machine. @@ -3726,11 +3937,14 @@ which is why it's currently left out of your copy. believes it found an infinite loop in the C<@ISA> hierarchy. This is a crude check that bails out after 100 levels of C<@ISA> depth. -=item Recursive inheritance detected while looking for method %s +=item refcnt_dec: fd %d%s -(F) More than 100 levels of inheritance were encountered while invoking -a method. Probably indicates an unintended loop in your inheritance -hierarchy. +=item refcnt: fd %d%s + +=item refcnt_inc: fd %d%s + +(P) Perl's I/O implementation failed an internal consistency check. If +you see this message, something is very wrong. =item Reference found where even-sized list expected @@ -3752,30 +3966,21 @@ Doing so has no effect. =item Reference miscount in sv_replace() (W internal) The internal sv_replace() function was handed a new SV with -a reference count of other than 1. +a reference count other than 1. =item Reference to invalid group 0 (F) You used C<\g0> or similar in a regular expression. You may refer to capturing parentheses only with strictly positive integers (normal backreferences) or with strictly negative integers (relative -backreferences), but using 0 does not make sense. +backreferences). Using 0 does not make sense. =item Reference to nonexistent group in regex; marked by <-- HERE in m/%s/ (F) You used something like C<\7> in your regular expression, but there are -not at least seven sets of capturing parentheses in the expression. If you -wanted to have the character with value 7 inserted into the regular expression, -prepend a zero to make the number at least two digits: C<\07> - -The <-- HERE shows in the regular expression about where the problem was -discovered. - -=item Reference to nonexistent or unclosed group in regex; marked by <-- HERE in m/%s/ - -(F) You used something like C<\g{-7}> in your regular expression, but there are -not at least seven sets of closed capturing parentheses in the expression before -where the C<\g{-7}> was located. +not at least seven sets of capturing parentheses in the expression. If +you wanted to have the character with ordinal 7 inserted into the regular +expression, prepend zeroes to make it three digits long: C<\007> The <-- HERE shows in the regular expression about where the problem was discovered. @@ -3783,18 +3988,18 @@ discovered. =item Reference to nonexistent named group in regex; marked by <-- HERE in m/%s/ (F) You used something like C<\k'NAME'> or C<< \k<NAME> >> in your regular -expression, but there is no corresponding named capturing parentheses such -as C<(?'NAME'...)> or C<(?<NAME>...). Check if the name has been spelled -correctly both in the backreference and the declaration. +expression, but there is no corresponding named capturing parentheses +such as C<(?'NAME'...)> or C<< (?<NAME>...) >>. Check if the name has been +spelled correctly both in the backreference and the declaration. The <-- HERE shows in the regular expression about where the problem was discovered. -=item (?(DEFINE)....) does not allow branches in regex; marked by <-- HERE in m/%s/ +=item Reference to nonexistent or unclosed group in regex; marked by <-- HERE in m/%s/ -(F) You used something like C<(?(DEFINE)...|..)> which is illegal. The -most likely cause of this error is that you left out a parenthesis inside -of the C<....> part. +(F) You used something like C<\g{-7}> in your regular expression, but there +are not at least seven sets of closed capturing parentheses in the +expression before where the C<\g{-7}> was located. The <-- HERE shows in the regular expression about where the problem was discovered. @@ -3804,6 +4009,26 @@ discovered. (P) The regular expression engine got confused by what the regular expression compiler gave it. +=item Regexp modifier "/%c" may appear a maximum of twice + +=item Regexp modifier "/%c" may not appear twice + +(F syntax, regexp) The regular expression pattern had too many occurrences +of the specified modifier. Remove the extraneous ones. + +=item Regexp modifier "%c" may not appear after the "-" + +(F regexp) Turning off the given modifier has the side effect of turning +on another one. Perl currently doesn't allow this. Reword the regular +expression to use the modifier you want to turn on (and place it before +the minus), instead of the one you want to turn off. + +=item Regexp modifiers "/%c" and "/%c" are mutually exclusive + +(F syntax, regexp) The regular expression pattern had more than one of these +mutually exclusive modifiers. Retain only the modifier that is +supposed to be there. + =item Regexp out of space (P) A "can't happen" error, because safemalloc() should have caught it @@ -3824,7 +4049,7 @@ are meaningless. =item Reversed %s= operator (W syntax) You wrote your assignment operator backwards. The = must -always comes last, to avoid ambiguity with subsequent unary operators. +always come last, to avoid ambiguity with subsequent unary operators. =item rewinddir() attempted on invalid dirhandle %s @@ -3889,16 +4114,16 @@ C<foo ? 0 : 1>) leading to some ambiguous constructions being wrongly parsed. One way to disambiguate the parsing is to put parentheses around the conditional expression, i.e. C<(foo) ? 0 : 1>. -=item %sseek() on unopened filehandle - -(W unopened) You tried to use the seek() or sysseek() function on a -filehandle that was either never opened or has since been closed. - =item seekdir() attempted on invalid dirhandle %s (W io) The dirhandle you are doing a seekdir() on is either closed or not really a dirhandle. Check your control flow. +=item %sseek() on unopened filehandle + +(W unopened) You tried to use the seek() or sysseek() function on a +filehandle that was either never opened or has since been closed. + =item select not implemented (F) This machine doesn't implement the select() system call. @@ -3943,9 +4168,12 @@ where the problem was discovered. See L<perlre>. (F) You used a regular expression extension that doesn't make sense. The <-- HERE shows in the regular expression about where the problem was -discovered. See L<perlre>. +discovered. This happens when using the C<(?^...)> construct to tell +Perl to use the default regular expression modifiers, and you +redundantly specify a default modifier. For other +causes, see L<perlre>. -=item Sequence \\%s... not terminated in regex; marked by <-- HERE in m/%s/ +=item Sequence \%s... not terminated in regex; marked by <-- HERE in m/%s/ (F) The regular expression expects a mandatory argument following the escape sequence and this has been omitted or incorrectly written. @@ -3959,18 +4187,18 @@ L<perlre>. =item Sequence (?{...}) not terminated or not {}-balanced in regex; marked by <-- HERE in m/%s/ -(F) If the contents of a (?{...}) clause contains braces, they must balance -for Perl to properly detect the end of the clause. The <-- HERE shows in +(F) If the contents of a (?{...}) clause contain braces, they must balance +for Perl to detect the end of the clause properly. The <-- HERE shows in the regular expression about where the problem was discovered. See L<perlre>. -=item 500 Server error +=item Z<>500 Server error See Server error. =item Server error -This is the error message generally seen in a browser window when trying +(A) This is the error message generally seen in a browser window when trying to run a CGI program (including SSI) over the web. The actual error text varies widely from server to server. The most frequently-seen variants are "500 Server error", "Method (something) not permitted", "Document @@ -4028,16 +4256,6 @@ didn't think so. forget to check the return value of your socket() call? See L<perlfunc/setsockopt>. -=item Setuid/gid script is writable by world - -(F) The setuid emulator won't run a script that is writable by the -world, because the world might have written on it already. - -=item Setuid script not plain file - -(F) The setuid emulator won't run a script that isn't read from a file, -but from a socket, a pipe or another device. - =item shm%s not implemented (F) You don't have System V shared memory IPC on your system. @@ -4108,6 +4326,12 @@ unless there was a failure. You probably wanted to use system() instead, which does return. To suppress this warning, put the exec() in a block by itself. +=item "state" variable %s can't be in a package + +(F) Lexically scoped variables aren't in a package, so it doesn't make +sense to try to declare one with a package qualifier on the front. Use +local() if you want to localize a package variable. + =item stat() on unopened filehandle %s (W unopened) You tried to use the stat() function on a filehandle that @@ -4157,7 +4381,7 @@ assignment or as a subroutine argument for example). =item sv_upgrade from type %d down to type %d -(P) Perl tried to force the upgrade an SV to a type which was actually +(P) Perl tried to force the upgrade of an SV to a type which was actually inferior to its current type. =item Switch (?(condition)... contains too many branches in regex; marked by <-- HERE in m/%s/ @@ -4174,16 +4398,16 @@ discovered. See L<perlre>. =item Switch condition not recognized in regex; marked by <-- HERE in m/%s/ -(F) If the argument to the (?(...)if-clause|else-clause) construct is a -number, it can be only a number. The <-- HERE shows in the regular expression -about where the problem was discovered. See L<perlre>. +(F) If the argument to the (?(...)if-clause|else-clause) construct is +a number, it can be only a number. The <-- HERE shows in the regular +expression about where the problem was discovered. See L<perlre>. =item switching effective %s is not implemented (F) While under the C<use filetest> pragma, we cannot switch the real and effective uids or gids. -=item %s syntax +=item %s syntax OK (F) The final summary message when a C<perl -c> succeeds. @@ -4251,16 +4475,16 @@ know about your kind of stdio. You'll have to use a filename instead. (F) You tried to use C<goto> to reach a label that was too deeply nested for Perl to reach. Perl is doing you a favor by refusing. -=item tell() on unopened filehandle - -(W unopened) You tried to use the tell() function on a filehandle that -was either never opened or has since been closed. - =item telldir() attempted on invalid dirhandle %s (W io) The dirhandle you tried to telldir() is either closed or not really a dirhandle. Check your control flow. +=item tell() on unopened filehandle + +(W unopened) You tried to use the tell() function on a filehandle that +was either never opened or has since been closed. + =item That use of $[ is unsupported (F) Assignment to C<$[> is now strictly circumscribed, and interpreted @@ -4286,7 +4510,7 @@ will deny it. =item The %s function is unimplemented -The function indicated isn't implemented on this architecture, according +(F) The function indicated isn't implemented on this architecture, according to the probings of Configure. =item The stat preceding %s wasn't an lstat @@ -4425,6 +4649,11 @@ certain type. Arrays must be @NAME or C<@{EXPR}>. Hashes must be %NAME or C<%{EXPR}>. No implicit dereferencing is allowed--use the {EXPR} forms as an explicit dereference. See L<perlref>. +=item Type of argument to %s must be unblessed hashref or arrayref + +(F) You called C<keys>, C<values> or C<each> with a scalar argument that +was not a reference to an unblessed hash or array. + =item umask not implemented (F) Your machine doesn't implement the umask function and you tried to @@ -4500,16 +4729,25 @@ Check the #! line, or manually feed your script into Perl yourself. (F) The unexec() routine failed for some reason. See your local FSF representative, who probably put it there in the first place. -=item Unicode non-character %s is illegal for interchange +=item Unicode non-character U+%X is illegal for open interchange -(W utf8) Certain codepoints, such as U+FFFE and U+FFFF, are defined by the +(W utf8, nonchar) Certain codepoints, such as U+FFFE and U+FFFF, are +defined by the Unicode standard to be non-characters. Those are legal codepoints, but are reserved for internal use; so, applications shouldn't attempt to exchange -them. In some cases, this message is also given if you use a codepoint that -isn't in Unicode--that is it is above the legal maximum of U+10FFFF. These -aren't legal at all in Unicode, so they are illegal for interchange, but can be -used internally in a Perl program. If you know what you are doing you can turn -off this warning by C<no warnings 'utf8';>. +them. If you know what you are doing you can turn +off this warning by C<no warnings 'nonchar';>. + +=item Unicode surrogate U+%X is illegal in UTF-8 + +(W utf8, surrogate) You had a UTF-16 surrogate in a context where they are +not considered acceptable. These code points, between U+D800 and +U+DFFF (inclusive), are used by Unicode only for UTF-16. However, Perl +internally allows all unsigned integer code points (up to the size limit +available on your platform), including surrogates. But these can cause +problems when being input or output, which is likely where this message +came from. If you really really know what you are doing you can turn +off this warning by C<no warnings 'surrogate';>. =item Unknown BYTEORDER @@ -4540,45 +4778,50 @@ subvert Perl's population of %ENV for nefarious purposes. =item Unknown "re" subpragma '%s' (known ones are: %s) -You tried to use an unknown subpragma of the "re" pragma. +(W) You tried to use an unknown subpragma of the "re" pragma. -=item Unknown switch condition (?(%.2s in regex; marked by <-- HERE in m/%s/ +=item Unknown switch condition (?(%s in regex; marked by <-- HERE in m/%s/ (F) The condition part of a (?(condition)if-clause|else-clause) construct -is not known. The condition may be lookahead or lookbehind (the condition -is true if the lookahead or lookbehind is true), a (?{...}) construct (the -condition is true if the code evaluates to a true value), or a number (the -condition is true if the set of capturing parentheses named by the number -matched). +is not known. The condition must be one of the following: + + (1) (2) ... true if 1st, 2nd, etc., capture matched + (<NAME>) ('NAME') true if named capture matched + (?=...) (?<=...) true if subpattern matches + (?!...) (?<!...) true if subpattern fails to match + (?{ CODE }) true if code returns a true value + (R) true if evaluating inside recursion + (R1) (R2) ... true if directly inside capture group 1, 2, etc. + (R&NAME) true if directly inside named capture + (DEFINE) always false; for defining named subpatterns The <-- HERE shows in the regular expression about where the problem was discovered. See L<perlre>. =item Unknown Unicode option letter '%c' -You specified an unknown Unicode option. See L<perlrun> documentation +(F) You specified an unknown Unicode option. See L<perlrun> documentation of the C<-C> switch for the list of known options. =item Unknown Unicode option value %x -You specified an unknown Unicode option. See L<perlrun> documentation +(F) You specified an unknown Unicode option. See L<perlrun> documentation of the C<-C> switch for the list of known options. -=item Unknown warnings category '%s' - -(F) An error issued by the C<warnings> pragma. You specified a warnings -category that is unknown to perl at this point. - -Note that if you want to enable a warnings category registered by a module -(e.g. C<use warnings 'File::Find'>), you must have imported this module - =item Unknown verb pattern '%s' in regex; marked by <-- HERE in m/%s/ (F) You either made a typo or have incorrectly put a C<*> quantifier after an open brace in your pattern. Check the pattern and review L<perlre> for details on legal verb patterns. -first. +=item Unknown warnings category '%s' + +(F) An error issued by the C<warnings> pragma. You specified a warnings +category that is unknown to perl at this point. + +Note that if you want to enable a warnings category registered by a +module (e.g. C<use warnings 'File::Find'>), you must have loaded this +module first. =item unmatched [ in regex; marked by <-- HERE in m/%s/ @@ -4614,7 +4857,7 @@ subroutine. in your Perl script (or eval) near the specified column. Perhaps you tried to run a compressed script, a binary program, or a directory as a Perl program. -=item Unrecognized escape \\%c in character class passed through in regex; marked by <-- HERE in m/%s/ +=item Unrecognized escape \%c in character class passed through in regex; marked by <-- HERE in m/%s/ (W regexp) You used a backslash-character combination which is not recognized by Perl inside character classes. The character was @@ -4622,16 +4865,16 @@ understood literally, but this may change in a future version of Perl. The <-- HERE shows in the regular expression about where the escape was discovered. -=item Unrecognized escape \\%c passed through +=item Unrecognized escape \%c passed through (W misc) You used a backslash-character combination which is not recognized by Perl. The character was understood literally, but this may change in a future version of Perl. -=item Unrecognized escape \\%c passed through in regex; marked by <-- HERE in m/%s/ +=item Unrecognized escape \%s passed through in regex; marked by <-- HERE in m/%s/ (W regexp) You used a backslash-character combination which is not -recognized by Perl. The character was understood literally, but this may +recognized by Perl. The character(s) were understood literally, but this may change in a future version of Perl. The <-- HERE shows in the regular expression about where the escape was discovered. @@ -4701,16 +4944,6 @@ character to get your parentheses to balance. See L<attributes>. compressed integer format and could not be converted to an integer. See L<perlfunc/pack>. -=item Unterminated verb pattern in regex; marked by <-- HERE in m/%s/ - -(F) You used a pattern of the form C<(*VERB)> but did not terminate -the pattern with a C<)>. Fix the pattern and retry. - -=item Unterminated verb pattern argument in regex; marked by <-- HERE in m/%s/ - -(F) You used a pattern of the form C<(*VERB:ARG)> but did not terminate -the pattern with a C<)>. Fix the pattern and retry. - =item Unterminated \g{...} pattern in regex; marked by <-- HERE in m/%s/ (F) You missed a close brace on a \g{..} pattern (group reference) in @@ -4723,6 +4956,16 @@ a term, so it's looking for the corresponding right angle bracket, and not finding it. Chances are you left some needed parentheses out earlier in the line, and you really meant a "less than". +=item Unterminated verb pattern argument in regex; marked by <-- HERE in m/%s/ + +(F) You used a pattern of the form C<(*VERB:ARG)> but did not terminate +the pattern with a C<)>. Fix the pattern and retry. + +=item Unterminated verb pattern in regex; marked by <-- HERE in m/%s/ + +(F) You used a pattern of the form C<(*VERB)> but did not terminate +the pattern with a C<)>. Fix the pattern and retry. + =item untie attempted while %d inner references still exist (W untie) A copy of the object returned from C<tie> (or C<tied>) was @@ -4880,13 +5123,15 @@ modifier is not presently meaningful in substitutions. use the /g modifier. Currently, /c is meaningful only when /g is used. (This may change in the future.) -=item Use of := for an empty attribute list is deprecated +=item Use of := for an empty attribute list is not allowed + +(F) The construction C<my $x := 42> used to parse as equivalent to +C<my $x : = 42> (applying an empty attribute list to C<$x>). +This construct was deprecated in 5.12.0, and has now been made a syntax +error, so C<:=> can be reclaimed as a new operator in the future. -(D deprecated) The construction C<my $x := 42> currently -parses correctly in perl, being equivalent to C<my $x : = 42> -(applying an empty attribute list to C<$x>). This useless -construct is now deprecated, so C<:=> can be reclaimed as a new -operator in the future. +If you need an empty attribute list, for example in a code generator, add +a space before the C<=>. =item Use of freed value in iteration @@ -4919,11 +5164,11 @@ scope is deprecated and should be avoided. =item Use of inherited AUTOLOAD for non-method %s() is deprecated -(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD> subroutines -are looked up as methods (using the C<@ISA> hierarchy) even when the -subroutines to be autoloaded were called as plain functions (e.g. -C<Foo::bar()>), not as methods (e.g. C<< Foo->bar() >> or C<< -$obj->bar() >>). +(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD> +subroutines are looked up as methods (using the C<@ISA> hierarchy) +even when the subroutines to be autoloaded were called as plain +functions (e.g. C<Foo::bar()>), not as methods (e.g. C<< Foo->bar() >> or +C<< $obj->bar() >>). This bug will be rectified in future by using method lookup only for methods' C<AUTOLOAD>s. However, there is a significant base of existing @@ -4941,15 +5186,6 @@ In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);> you should remove AutoLoader from @ISA and change C<use AutoLoader;> to C<use AutoLoader 'AUTOLOAD';>. -=item Use of octal value above 377 is deprecated - -(D deprecated, W regexp) There is a constant in the regular expression whose -value is interpeted by Perl as octal and larger than 377 (255 decimal, 0xFF -hex). Perl may take this to mean different things depending on the rest of -the regular expression. If you meant such an octal value, convert it to -hexadecimal and use C<\xHH> or C<\x{HH}> instead. If you meant to have -part of it mean a backreference, use C<\g> for that. See L<perlre>. - =item Use of %s in printf format not supported (F) You attempted to use a feature of printf that is accessible from @@ -4967,12 +5203,37 @@ old way has bad side effects. it already went past any symlink you are presumably trying to look for. The operation returned C<undef>. Use a filename instead. -=item Use of "package" with no arguments is deprecated +=item Use of %s on a handle without * is deprecated -(D deprecated) You used the C<package> keyword without specifying a package -name. So no namespace is current at all. Using this can cause many -otherwise reasonable constructs to fail in baffling ways. C<use strict;> -instead. +(D deprecated) You used C<tie>, C<tied> or C<untie> on a scalar but that +scalar happens to hold a typeglob, which means its filehandle will +be tied. If you mean to tie a handle, use an explicit * as in +C<tie *$handle>. + +This is a long-standing bug that will be removed in Perl 5.16, as +there is currently no way to tie the scalar itself when it holds +a typeglob, and no way to untie a scalar that has had a typeglob +assigned to it. + +=item Use of ?PATTERN? without explicit operator is deprecated + +(D deprecated) You have written something like C<?\w?>, for a regular +expression that matches only once. Starting this term directly with +the question mark delimiter is now deprecated, so that the question mark +will be available for use in new operators in the future. Write C<m?\w?> +instead, explicitly using the C<m> operator: the question mark delimiter +still invokes match-once behaviour. + +=item Use of qw(...) as parentheses is deprecated + +(D deprecated) You have something like C<foreach $x qw(a b c) {...}>, +using a C<qw(...)> list literal where a parenthesised expression is +expected. Historically the parser fooled itself into thinking that +C<qw(...)> literals were always enclosed in parentheses, and as a result +you could sometimes omit parentheses around them. (You could never do +the C<foreach qw(a b c) {...}> that you might have expected, though.) +The parser no longer lies to itself in this way. Wrap the list literal +in parentheses, like C<foreach $x (qw(a b c)) {...}>. =item Use of reference "%s" as array index @@ -4982,8 +5243,8 @@ to be huge numbers, and so usually indicates programmer error. If you really do mean it, explicitly numify your reference, like so: C<$array[0+$ref]>. This warning is not given for overloaded objects, -either, because you can overload the numification and stringification -operators and then you assumably know what you are doing. +however, because you can overload the numification and stringification +operators and then you presumably know what you are doing. =item Use of reserved word "%s" is deprecated @@ -5036,23 +5297,32 @@ removed in a future version. Currently all but the first one are discarded when used in a regular expression pattern bracketed character class. -=item Using just the first characters returned by \N{} +=item Using !~ with %s doesn't make sense + +(F) Using the C<!~> operator with C<s///r>, C<tr///r> or C<y///r> is +currently reserved for future use, as the exact behaviour has not +been decided. (Simply returning the boolean opposite of the +modified string is usually not particularly useful.) + +=item User-defined case-mapping '%s' is deprecated -(W) A charnames handler may return a sequence of characters. There is a finite -limit as to the number of characters that can be used, which this sequence -exceeded. In the message, the characters in the sequence are separated by -dots, and each is shown by its ordinal in hex. Anything to the left of the -C<HERE> was retained; anything to the right was discarded. +(W deprecated) You defined a function, such as C<ToLower> that overrides +the standard case mapping, such as C<lc()> gives. This feature is being +deprecated due to its many issues, as documented in +L<perlunicode/User-Defined Case Mappings (for serious hackers only)>. +It is planned to remove this feature in Perl 5.16. A CPAN module +providing improved functionality is being prepared. -=item UTF-16 surrogate %s +=item UTF-16 surrogate U+%X -(W utf8) You tried to generate half of a UTF-16 surrogate by -requesting a Unicode character between the code points 0xD800 and -0xDFFF (inclusive). That range is reserved exclusively for the use of -UTF-16 encoding (by having two 16-bit UCS-2 characters); but Perl -encodes its characters in UTF-8, so what you got is a very illegal -character. If you really really know what you are doing you can turn off -this warning by C<no warnings 'utf8';>. +(W utf8, surrogate) You had a UTF-16 surrogate in a context where they are +not considered acceptable. These code points, between U+D800 and +U+DFFF (inclusive), are used by Unicode only for UTF-16. However, Perl +internally allows all unsigned integer code points (up to the size limit +available on your platform), including surrogates. But these can cause +problems when being input or output, which is likely where this message +came from. If you really really know what you are doing you can turn +off this warning by C<no warnings 'surrogate';>. =item Value of %s can be "0"; test with defined() @@ -5102,8 +5372,8 @@ executed, so its $a is not available for capture. =item Variable "%s" is not imported%s -(F) While "use strict" in effect, you referred to a global variable that -you apparently thought was imported from another module, because +(W misc) With "use strict" in effect, you referred to a global variable +that you apparently thought was imported from another module, because something else of the same name (usually a subroutine) is exported by that module. It usually means you put the wrong funny character on the front of your variable. @@ -5115,11 +5385,11 @@ known at compile time. See L<perlre>. =item "%s" variable %s masks earlier declaration in same %s -(W misc) A "my", "our" or "state" variable has been redeclared in the current -scope or statement, effectively eliminating all access to the previous -instance. This is almost always a typographical error. Note that the -earlier variable will still exist until the end of the scope or until -all closure referents to it are destroyed. +(W misc) A "my", "our" or "state" variable has been redeclared in the +current scope or statement, effectively eliminating all access to the +previous instance. This is almost always a typographical error. Note +that the earlier variable will still exist until the end of the scope +or until all closure referents to it are destroyed. =item Variable syntax @@ -5209,7 +5479,7 @@ filehandle with an encoding, see L<open> and L<perlfunc/binmode>. (F) The count in the (un)pack template may be replaced by C<[TEMPLATE]> only if C<TEMPLATE> always matches the same amount of packed bytes that can be -determined from the template alone. This is not possible if it contains an +determined from the template alone. This is not possible if it contains any of the codes @, /, U, u, w or a *-length. Redesign the template. =item write() on closed filehandle %s @@ -5217,9 +5487,9 @@ of the codes @, /, U, u, w or a *-length. Redesign the template. (W closed) The filehandle you're writing to got itself closed sometime before now. Check your control flow. -=item %s "\x%s" does not map to Unicode +=item %s "\x%X" does not map to Unicode -When reading in different encodings Perl tries to map everything +(F) When reading in different encodings Perl tries to map everything into Unicode characters. The bytes you read in are not legal in this encoding, for example diff --git a/Master/tlpkg/tlperl/lib/pods/perldoc.pod b/Master/tlpkg/tlperl/lib/pods/perldoc.pod index 883a6184603..7a609590349 100644 --- a/Master/tlpkg/tlperl/lib/pods/perldoc.pod +++ b/Master/tlpkg/tlperl/lib/pods/perldoc.pod @@ -80,7 +80,7 @@ Consider arguments as file names; no search in directories will be performed. =item B<-f> I<perlfunc> -The B<-f> option followed by the name of a perl built in function will +The B<-f> option followed by the name of a perl built-in function will extract the documentation of this function from L<perlfunc>. Example: @@ -160,7 +160,7 @@ You can use C<-w optionname> (without a value) as shorthand for C<-w optionname:I<TRUE>>. This is presumably useful in cases of on/off features like: C<-w page_numbering>. -You can use a "=" instead of the ":", as in: C<-w textsize=15>. This +You can use an "=" instead of the ":", as in: C<-w textsize=15>. This might be more (or less) convenient, depending on what shell you use. =item B<-X> @@ -172,12 +172,12 @@ qualified filenames, one per line. =item B<-L> I<language_code> -This allows to specify the I<language code> for desired language translation. -If C<POD2::E<lt>language_codeE<gt>> package doesn't exist (or isn't installed -in your system), the switch will be ignored. -All available translation packages should be found under the C<POD2::> -namespace. See L<POD2::IT> (or L<POD2::FR>) in order to see how to create and -integrate new localized C<POD2::*> pod documentation packages in +This allows one to specify the I<language code> for the desired language +translation. If the C<POD2::E<lt>language_codeE<gt>> package isn't +installed in your system, the switch is ignored. +All available translation packages are to be found under the C<POD2::> +namespace. See L<POD2::IT> (or L<POD2::FR>) to see how to create new +localized C<POD2::*> documentation packages and integrate them into L<Pod::Perldoc>. =item B<PageName|ModuleName|ProgramName> @@ -226,7 +226,7 @@ command line arguments. Useful values for C<PERLDOC> include C<-oman>, C<-otext>, C<-otk>, C<-ortf>, C<-oxml>, and so on, depending on what modules you have on hand; or -exactly specify the formatter class with C<-MPod::Perldoc::ToMan> +the formatter class may be specified exactly with C<-MPod::Perldoc::ToMan> or the like. C<perldoc> also searches directories diff --git a/Master/tlpkg/tlperl/lib/pods/perlebcdic.pod b/Master/tlpkg/tlperl/lib/pods/perlebcdic.pod index f17891237a0..6affdd7b8aa 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlebcdic.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlebcdic.pod @@ -1,3 +1,5 @@ +=encoding utf8 + =head1 NAME perlebcdic - Considerations for running Perl on EBCDIC platforms @@ -6,7 +8,7 @@ perlebcdic - Considerations for running Perl on EBCDIC platforms An exploration of some of the issues facing Perl programmers on EBCDIC based computers. We do not cover localization, -internationalization, or multi byte character set issues other +internationalization, or multi-byte character set issues other than some discussion of UTF-8 and UTF-EBCDIC. Portions that are still incomplete are marked with XXX. @@ -24,7 +26,7 @@ set of integers running from 0 to 127 (decimal) that imply character interpretation by the display and other systems of computers. The range 0..127 can be covered by setting the bits in a 7-bit binary -digit, hence the set is sometimes referred to as a "7-bit ASCII". +digit, hence the set is sometimes referred to as "7-bit ASCII". ASCII was described by the American National Standards Institute document ANSI X3.4-1986. It was also described by ISO 646:1991 (with localization for currency symbols). The full ASCII set is @@ -61,10 +63,10 @@ also known as CCSID 819 (or sometimes 0819 or even 00819). =head2 EBCDIC The Extended Binary Coded Decimal Interchange Code refers to a -large collection of single and multi byte coded character sets that are +large collection of single- and multi-byte coded character sets that are different from ASCII or ISO 8859-1 and are all slightly different from each other; they typically run on host computers. The EBCDIC encodings derive from -8 bit byte extensions of Hollerith punched card encodings. The layout on the +8-bit byte extensions of Hollerith punched card encodings. The layout on the cards was such that high bits were set for the upper and lower case alphabet characters [a-z] and [A-Z], but there were gaps within each Latin alphabet range. @@ -122,8 +124,8 @@ The problem is: which code points to use for code points less than 256? In EBCDIC, for the low 256 the EBCDIC code points are used. This means that the equivalences - pack("U", ord($character)) eq $character - unpack("U", $character) == ord $character + pack("U", ord($character)) eq $character + unpack("U", $character) == ord $character will hold. (If Unicode code points were applied consistently over all the possible code points, pack("U",ord("A")) would in EBCDIC @@ -180,23 +182,23 @@ 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'; + use Encode 'from_to'; - my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' ); + my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' ); - # $a is in EBCDIC code points - from_to($a, $ebcdic{ord '^'}, 'latin1'); - # $a is ISO 8859-1 code points + # $a is in EBCDIC code points + from_to($a, $ebcdic{ord '^'}, 'latin1'); + # $a is ISO 8859-1 code points and from Latin-1 code points to EBCDIC code points - use Encode 'from_to'; + use Encode 'from_to'; - my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' ); + my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' ); - # $a is ISO 8859-1 code points - from_to($a, 'latin1', $ebcdic{ord '^'}); - # $a is in EBCDIC code points + # $a is ISO 8859-1 code points + from_to($a, 'latin1', $ebcdic{ord '^'}); + # $a is in EBCDIC code points For doing I/O it is suggested that you use the autotranslating features of PerlIO, see L<perluniintro>. @@ -237,7 +239,7 @@ s/CAPITAL LETTER// in some cases, and s/SMALL LETTER ([A-Z])/\l$1/ in some other cases. The "names" of the controls listed here are the Unicode Version 1 names, except for the few that don't have names, in which case the names in the Wikipedia article were used -(L<http://en.wikipedia.org/wiki/C0_and_C1_control_codes>. +(L<http://en.wikipedia.org/wiki/C0_and_C1_control_codes>). The differences between the 0037 and 1047 sets are flagged with ***. The differences between the 1047 and POSIX-BC sets are flagged with ###. All ord() numbers listed are decimal. If you @@ -252,7 +254,8 @@ work with a pod2_other_format translation) through: =back perl -ne 'if(/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \ - -e '{printf("%s%-9o%-9o%-9o%o\n",$1,$2,$3,$4,$5)}' perlebcdic.pod + -e '{printf("%s%-9.03o%-9.03o%-9.03o%.03o\n",$1,$2,$3,$4,$5)}' \ + perlebcdic.pod If you want to retain the UTF-x code points then in script form you might want to write: @@ -263,20 +266,25 @@ might want to write: =back - open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!"; - while (<FH>) { - if (/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/) { - if ($7 ne '' && $9 ne '') { - printf("%s%-9o%-9o%-9o%-9o%-3o.%-5o%-3o.%o\n",$1,$2,$3,$4,$5,$6,$7,$8,$9); - } - elsif ($7 ne '') { - printf("%s%-9o%-9o%-9o%-9o%-3o.%-5o%o\n",$1,$2,$3,$4,$5,$6,$7,$8); - } - else { - printf("%s%-9o%-9o%-9o%-9o%-9o%o\n",$1,$2,$3,$4,$5,$6,$8); - } - } - } + open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!"; + while (<FH>) { + if (/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/) + { + if ($7 ne '' && $9 ne '') { + printf( + "%s%-9.03o%-9.03o%-9.03o%-9.03o%-3o.%-5o%-3o.%.03o\n", + $1,$2,$3,$4,$5,$6,$7,$8,$9); + } + elsif ($7 ne '') { + printf("%s%-9.03o%-9.03o%-9.03o%-9.03o%-3o.%-5o%.03o\n", + $1,$2,$3,$4,$5,$6,$7,$8); + } + else { + printf("%s%-9.03o%-9.03o%-9.03o%-9.03o%-9.03o%.03o\n", + $1,$2,$3,$4,$5,$6,$8); + } + } + } If you would rather see this table listing hexadecimal values then run the table through: @@ -288,7 +296,8 @@ run the table through: =back perl -ne 'if(/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \ - -e '{printf("%s%-9X%-9X%-9X%X\n",$1,$2,$3,$4,$5)}' perlebcdic.pod + -e '{printf("%s%-9.02X%-9.02X%-9.02X%.02X\n",$1,$2,$3,$4,$5)}' \ + perlebcdic.pod Or, in order to retain the UTF-x code points in hexadecimal: @@ -298,20 +307,25 @@ Or, in order to retain the UTF-x code points in hexadecimal: =back - open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!"; - while (<FH>) { - if (/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/) { - if ($7 ne '' && $9 ne '') { - printf("%s%-9X%-9X%-9X%-9X%-2X.%-6X%-2X.%X\n",$1,$2,$3,$4,$5,$6,$7,$8,$9); - } - elsif ($7 ne '') { - printf("%s%-9X%-9X%-9X%-9X%-2X.%-6X%X\n",$1,$2,$3,$4,$5,$6,$7,$8); - } - else { - printf("%s%-9X%-9X%-9X%-9X%-9X%X\n",$1,$2,$3,$4,$5,$6,$8); - } - } - } + open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!"; + while (<FH>) { + if (/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/) + { + if ($7 ne '' && $9 ne '') { + printf( + "%s%-9.02X%-9.02X%-9.02X%-9.02X%-2X.%-6.02X%02X.%02X\n", + $1,$2,$3,$4,$5,$6,$7,$8,$9); + } + elsif ($7 ne '') { + printf("%s%-9.02X%-9.02X%-9.02X%-9.02X%-2X.%-6.02X%02X\n", + $1,$2,$3,$4,$5,$6,$7,$8); + } + else { + printf("%s%-9.02X%-9.02X%-9.02X%-9.02X%-9.02X%02X\n", + $1,$2,$3,$4,$5,$6,$8); + } + } + } ISO 8859-1 CCSID CCSID CCSID 1047 @@ -583,7 +597,8 @@ ASCII + Latin-1 order then run the table through: =back - perl -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\ + perl \ + -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\ -e '{push(@l,$_)}' \ -e 'END{print map{$_->[0]}' \ -e ' sort{$a->[1] <=> $b->[1]}' \ @@ -598,11 +613,12 @@ If you would rather see it in CCSID 1047 order then change the number =back - perl -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\ - -e '{push(@l,$_)}' \ - -e 'END{print map{$_->[0]}' \ - -e ' sort{$a->[1] <=> $b->[1]}' \ - -e ' map{[$_,substr($_,61,3)]}@l;}' perlebcdic.pod + perl \ + -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\ + -e '{push(@l,$_)}' \ + -e 'END{print map{$_->[0]}' \ + -e ' sort{$a->[1] <=> $b->[1]}' \ + -e ' map{[$_,substr($_,61,3)]}@l;}' perlebcdic.pod If you would rather see it in POSIX-BC order then change the number 61 in the last line to 70, like this: @@ -613,7 +629,8 @@ If you would rather see it in POSIX-BC order then change the number =back - perl -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\ + perl \ + -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\ -e '{push(@l,$_)}' \ -e 'END{print map{$_->[0]}' \ -e ' sort{$a->[1] <=> $b->[1]}' \ @@ -656,7 +673,7 @@ However, it would be unwise to write tests such as: 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 +because "\n" is chr(13) and "\r" is chr(10) on the Macintosh (which is an ASCII platform) the second C<$is_ascii> test will lead to trouble there. To determine whether or not perl was built under an EBCDIC @@ -672,44 +689,49 @@ code page you can use the Config module like so: In order to convert a string of characters from one character set to another a simple list of numbers, such as in the right columns in the above table, along with perl's tr/// operator is all that is needed. -The data in the table are in ASCII order hence the EBCDIC columns -provide easy to use ASCII to EBCDIC operations that are also easily +The data in the table are in ASCII/Latin1 order, hence the EBCDIC columns +provide easy-to-use ASCII/Latin1 to EBCDIC operations that are also easily reversed. -For example, to convert ASCII to code page 037 take the output of the second -column from the output of recipe 0 (modified to add \\ characters) and use -it in tr/// like so: +For example, to convert ASCII/Latin1 to code page 037 take the output of the +second numbers column from the output of recipe 2 (modified to add '\' +characters) and use it in tr/// like so: $cp_037 = - '\000\001\002\003\234\011\206\177\227\215\216\013\014\015\016\017' . - '\020\021\022\023\235\205\010\207\030\031\222\217\034\035\036\037' . - '\200\201\202\203\204\012\027\033\210\211\212\213\214\005\006\007' . - '\220\221\026\223\224\225\226\004\230\231\232\233\024\025\236\032' . - '\040\240\342\344\340\341\343\345\347\361\242\056\074\050\053\174' . - '\046\351\352\353\350\355\356\357\354\337\041\044\052\051\073\254' . - '\055\057\302\304\300\301\303\305\307\321\246\054\045\137\076\077' . - '\370\311\312\313\310\315\316\317\314\140\072\043\100\047\075\042' . - '\330\141\142\143\144\145\146\147\150\151\253\273\360\375\376\261' . - '\260\152\153\154\155\156\157\160\161\162\252\272\346\270\306\244' . - '\265\176\163\164\165\166\167\170\171\172\241\277\320\335\336\256' . - '\136\243\245\267\251\247\266\274\275\276\133\135\257\250\264\327' . - '\173\101\102\103\104\105\106\107\110\111\255\364\366\362\363\365' . - '\175\112\113\114\115\116\117\120\121\122\271\373\374\371\372\377' . - '\134\367\123\124\125\126\127\130\131\132\262\324\326\322\323\325' . - '\060\061\062\063\064\065\066\067\070\071\263\333\334\331\332\237' ; + '\x00\x01\x02\x03\x37\x2D\x2E\x2F\x16\x05\x25\x0B\x0C\x0D\x0E\x0F' . + '\x10\x11\x12\x13\x3C\x3D\x32\x26\x18\x19\x3F\x27\x1C\x1D\x1E\x1F' . + '\x40\x5A\x7F\x7B\x5B\x6C\x50\x7D\x4D\x5D\x5C\x4E\x6B\x60\x4B\x61' . + '\xF0\xF1\xF2\xF3\xF4\xF5\xF6\xF7\xF8\xF9\x7A\x5E\x4C\x7E\x6E\x6F' . + '\x7C\xC1\xC2\xC3\xC4\xC5\xC6\xC7\xC8\xC9\xD1\xD2\xD3\xD4\xD5\xD6' . + '\xD7\xD8\xD9\xE2\xE3\xE4\xE5\xE6\xE7\xE8\xE9\xBA\xE0\xBB\xB0\x6D' . + '\x79\x81\x82\x83\x84\x85\x86\x87\x88\x89\x91\x92\x93\x94\x95\x96' . + '\x97\x98\x99\xA2\xA3\xA4\xA5\xA6\xA7\xA8\xA9\xC0\x4F\xD0\xA1\x07' . + '\x20\x21\x22\x23\x24\x15\x06\x17\x28\x29\x2A\x2B\x2C\x09\x0A\x1B' . + '\x30\x31\x1A\x33\x34\x35\x36\x08\x38\x39\x3A\x3B\x04\x14\x3E\xFF' . + '\x41\xAA\x4A\xB1\x9F\xB2\x6A\xB5\xBD\xB4\x9A\x8A\x5F\xCA\xAF\xBC' . + '\x90\x8F\xEA\xFA\xBE\xA0\xB6\xB3\x9D\xDA\x9B\x8B\xB7\xB8\xB9\xAB' . + '\x64\x65\x62\x66\x63\x67\x9E\x68\x74\x71\x72\x73\x78\x75\x76\x77' . + '\xAC\x69\xED\xEE\xEB\xEF\xEC\xBF\x80\xFD\xFE\xFB\xFC\xAD\xAE\x59' . + '\x44\x45\x42\x46\x43\x47\x9C\x48\x54\x51\x52\x53\x58\x55\x56\x57' . + '\x8C\x49\xCD\xCE\xCB\xCF\xCC\xE1\x70\xDD\xDE\xDB\xDC\x8D\x8E\xDF'; my $ebcdic_string = $ascii_string; - eval '$ebcdic_string =~ tr/' . $cp_037 . '/\000-\377/'; + eval '$ebcdic_string =~ tr/\000-\377/' . $cp_037 . '/'; To convert from EBCDIC 037 to ASCII just reverse the order of the tr/// arguments like so: my $ascii_string = $ebcdic_string; - eval '$ascii_string =~ tr/\000-\377/' . $cp_037 . '/'; + eval '$ascii_string =~ tr/' . $cp_037 . '/\000-\377/'; + +Similarly one could take the output of the third numbers column from recipe 2 +to obtain a C<$cp_1047> table. The fourth numbers column of the output from +recipe 2 could provide a C<$cp_posix_bc> table suitable for transcoding as +well. -Similarly one could take the output of the third column from recipe 0 to -obtain a C<$cp_1047> table. The fourth column of the output from recipe -0 could provide a C<$cp_posix_bc> table suitable for transcoding as well. +If you wanted to see the inverse tables, you would first have to sort on the +desired numbers column as in recipes 4, 5 or 6, then take the output of the +first numbers column. =head2 iconv @@ -728,11 +750,11 @@ or the inverse map: # OS/390 or z/OS example $ebcdic_data = `echo '$ascii_data'| iconv -f ISO8859-1 -t IBM-1047` -For other perl based conversion options see the Convert::* modules on CPAN. +For other perl-based conversion options see the Convert::* modules on CPAN. =head2 C RTL -The OS/390 and z/OS C run time libraries provide _atoe() and _etoa() functions. +The OS/390 and z/OS C run-time libraries provide _atoe() and _etoa() functions. =head1 OPERATOR DIFFERENCES @@ -756,8 +778,8 @@ 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@>)> -C<(chr(1) eq C<\cA>)>, and so on. Perl on EBCDIC platforms has been +as control characters in perl, e.g. C<(chr(0)> eq C<\c@>)> +C<(chr(1)> eq C<\cA>)>, and so on. Perl on EBCDIC platforms has been ported to take C<\c@> to chr(0) and C<\cA> to chr(1), etc. as well, but the thirty three characters that result depend on which code page you are using. The table below uses the standard acronyms for the controls. @@ -771,7 +793,7 @@ or regex, as it will absorb the terminator. But C<\c\I<X>> is a C<FILE SEPARATOR> concatenated with I<X> for all I<X>. chr ord 8859-1 0037 1047 && POSIX-BC - ------------------------------------------------------------------------ + ----------------------------------------------------------------------- \c? 127 <DEL> " " \c@ 0 <NUL> <NUL> <NUL> \cA 1 <SOH> <SOH> <SOH> @@ -851,7 +873,7 @@ recommend something similar to: Under the IBM OS/390 USS Web Server or WebSphere on z/OS for example you should instead write that as: - print "Content-type:\ttext/html\r\n\r\n"; # OK for DGW et alia + print "Content-type:\ttext/html\r\n\r\n"; # OK for DGW et al That is because the translation from EBCDIC to ASCII is done by the web server in this case (such code will not be appropriate for @@ -886,7 +908,7 @@ See the discussion of pack() above. =head1 REGULAR EXPRESSION DIFFERENCES -As of perl 5.005_03 the letter range regular expression such as +As of perl 5.005_03 the letter range regular expressions such as [A-Z] and [a-z] have been especially coded to not pick up gap characters. For example, characters such as E<ocirc> C<o WITH CIRCUMFLEX> that lie between I and J would not be matched by the @@ -1024,21 +1046,21 @@ output. =head1 SORTING -One big difference between ASCII based character sets and EBCDIC ones +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 platform the -two letter abbreviation for a physician comes before the two letter -for drive, that is: +letters compared to the digits. If sorted on an ASCII-based platform the +two-letter abbreviation for a physician comes before the two letter +abbreviation for drive; that is: - @sorted = sort(qw(Dr. dr.)); # @sorted holds ('Dr.','dr.') on ASCII, + @sorted = sort(qw(Dr. dr.)); # @sorted holds ('Dr.','dr.') on ASCII, # but ('dr.','Dr.') on EBCDIC -The property of lower case before uppercase letters in EBCDIC is +The property of lowercase before uppercase letters in EBCDIC is even carried to the Latin 1 EBCDIC pages such as 0037 and 1047. An example would be that E<Euml> C<E WITH DIAERESIS> (203) comes before E<euml> C<e WITH DIAERESIS> (235) on an ASCII platform, but the latter (83) comes before the former (115) on an EBCDIC platform. -(Astute readers will note that the upper case version of E<szlig> +(Astute readers will note that the uppercase version of E<szlig> C<SMALL LETTER SHARP S> is simply "SS" and that the upper case version of E<yuml> C<y WITH DIAERESIS> is not in the 0..255 range but it is at U+x0178 in Unicode, or C<"\x{178}"> in a Unicode enabled Perl). @@ -1054,7 +1076,7 @@ some user education. =head2 MONO CASE then sort data. -In order to minimize the expense of mono casing mixed test try to +In order to minimize the expense of mono casing mixed-case text, try to C<tr///> towards the character set case most employed within the data. If the data are primarily UPPERCASE non Latin 1 then apply tr/[a-z]/[A-Z]/ then sort(). If the data are primarily lowercase non Latin 1 then @@ -1069,7 +1091,7 @@ then sort(). Do note however that such Latin-1 manipulation does not address the E<yuml> C<y WITH DIAERESIS> character that will remain at code point 255 on ASCII platforms, but 223 on most EBCDIC platforms where it will sort to a place less than the EBCDIC numerals. With a -Unicode enabled Perl you might try: +Unicode-enabled Perl you might try: tr/^?/\x{178}/; @@ -1212,7 +1234,7 @@ that the @e2a array is filled in appropriately: =head2 Quoted-Printable encoding and decoding -On ASCII encoded platforms 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 @@ -1250,14 +1272,14 @@ omitted for brevity): $string =~ s/=([0-9A-Fa-f][0-9A-Fa-f])/chr $a2e[hex $1]/ge; $string =~ s/=[\n\r]+$//; -=head2 Caesarian ciphers +=head2 Caesarean ciphers The practice of shifting an alphabet one or more characters for encipherment dates back thousands of years and was explicitly detailed by Gaius Julius Caesar in his B<Gallic Wars> text. A single alphabet shift is sometimes referred to as a rotation and the shift amount is given as a number $n after the string 'rot' or "rot$n". Rot0 and rot26 would designate identity maps -on the 26 letter English version of the Latin alphabet. Rot13 has the +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 @@ -1279,16 +1301,16 @@ 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 platform and hashes stored on an EBCDIC based platform. +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 platforms. The details are system dependent +Internationalization (I18N) and localization (L10N) are supported at least +in principle even on EBCDIC platforms. The details are system-dependent and discussed under the L<perlebcdic/OS ISSUES> section below. -=head1 MULTI OCTET CHARACTER SETS +=head1 MULTI-OCTET CHARACTER SETS Perl may work with an internal UTF-EBCDIC encoding form for wide characters on EBCDIC platforms in a manner analogous to the way that it works with @@ -1298,7 +1320,7 @@ Legacy multi byte EBCDIC code pages XXX. =head1 OS ISSUES -There may be a few system dependent issues +There may be a few system-dependent issues of concern to EBCDIC Perl programmers. =head2 OS/400 @@ -1307,8 +1329,8 @@ of concern to EBCDIC Perl programmers. =item PASE -The PASE environment is runtime environment for OS/400 that can run -executables built for PowerPC AIX in OS/400, see L<perlos400>. PASE +The PASE environment is a runtime environment for OS/400 that can run +executables built for PowerPC AIX in OS/400; see L<perlos400>. PASE is ASCII-based, not EBCDIC-based as the ILE. =item IFS access diff --git a/Master/tlpkg/tlperl/lib/pods/perlembed.pod b/Master/tlpkg/tlperl/lib/pods/perlembed.pod index 5ecaed04d06..1b2e0c1bbcd 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlembed.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlembed.pod @@ -490,7 +490,7 @@ been wrapped here): SvREFCNT_dec(command); *match_list = get_av("array", 0); - num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/ + num_matches = av_len(*match_list) + 1; return num_matches; } @@ -931,7 +931,6 @@ Let's give it a try: #include <perl.h> /* we're going to embed two interpreters */ - /* we're going to embed two interpreters */ #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)" @@ -1070,34 +1069,6 @@ B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code. Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details. -=head1 Embedding Perl under Win32 - -In general, all of the source code shown here should work unmodified under -Windows. - -However, there are some caveats about the command-line examples shown. -For starters, backticks won't work under the Win32 native command shell. -The ExtUtils::Embed kit on CPAN ships with a script called -B<genmake>, which generates a simple makefile to build a program from -a single C source file. It can be used like this: - - C:\ExtUtils-Embed\eg> perl genmake interp.c - C:\ExtUtils-Embed\eg> nmake - C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}" - -You may wish to use a more robust environment such as the Microsoft -Developer Studio. In this case, run this to generate perlxsi.c: - - perl -MExtUtils::Embed -e xsinit - -Create a new project and Insert -> Files into Project: perlxsi.c, -perl.lib, and your own source files, e.g. interp.c. Typically you'll -find perl.lib in B<C:\perl\lib\CORE>, if not, you should see the -B<CORE> directory relative to C<perl -V:archlib>. The studio will -also need this path so it knows where to find Perl include files. -This path can be added via the Tools -> Options -> Directories menu. -Finally, select Build -> Build interp.exe and you're ready to go. - =head1 Hiding Perl_ If you completely hide the short forms of the Perl public API, @@ -1110,8 +1081,8 @@ you will have to write the explicit full form Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount); -(See L<perlguts/Background and PERL_IMPLICIT_CONTEXT for the explanation -of the C<aTHX_>.> ) Hiding the short forms is very useful for avoiding +(See L<perlguts/"Background and PERL_IMPLICIT_CONTEXT"> for the explanation +of the C<aTHX_>. ) Hiding the short forms is very useful for avoiding all sorts of nasty (C preprocessor or otherwise) conflicts with other software packages (Perl defines about 2400 APIs with these short names, take or leave few hundred, so there certainly is room for conflict.) diff --git a/Master/tlpkg/tlperl/lib/pods/perlepoc.pod b/Master/tlpkg/tlperl/lib/pods/perlepoc.pod index da33725acde..419e2e77121 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlepoc.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlepoc.pod @@ -12,18 +12,18 @@ Perl 5 README file for the EPOC Release 5 operating system. =head1 INTRODUCTION -EPOC is an OS for palmtops and mobile phones. For more informations look at: -http://www.symbian.com/ +EPOC is an OS for palmtops and mobile phones. For more information look +at: L<http://www.symbian.com/> This is a port of perl to the epocemx SDK by Eberhard Mattes, which itself uses the SDK by symbian. Essentially epocemx it is a POSIX look alike environment for the EPOC OS. For more information look at: -http://epocemx.sourceforge.net/ +L<http://epocemx.sourceforge.net/> perl and epocemx runs on Epoc Release 5 machines: Psion 5mx, 5mx Pro, Psion Revo, Psion Netbook and on the Ericsson M128. It may run on Epoc Release 3 Hardware (Series 5 classic), too. For more information about -this hardware please refer to http://www.psion.com/ +this hardware please refer to L<http://www.psion.com/> Vendors which like to have support for their devices are free to send me a sample. @@ -31,12 +31,12 @@ me a sample. =head1 INSTALLING PERL ON EPOC You can download a ready-to-install version from -http://www.oflebbe.de/perl/perl5.html +L<http://www.oflebbe.de/perl/perl5.html> You will need at least ~6MB free space in order to install and run perl. Please install the emxusr.sis package from -http://epocemx.sourceforge.net/ first. +L<http://epocemx.sourceforge.net/> first. Install perl.sis on the EPOC machine. If you do not know how to do that, consult your PsiWin documentation. @@ -145,7 +145,7 @@ Very special thanks to Eberhard Mattes for epocemx. =head1 AUTHOR Olaf Flebbe <olaf@oflebbe.de> -http://www.oflebbe.de/perl/perl5.html +L<http://www.oflebbe.de/perl/perl5.html> =head1 LAST UPDATE diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq.pod index 6eb7d2520aa..614ff564a93 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq.pod @@ -23,12 +23,11 @@ The perlfaq is an evolving document and you can read the latest version at http://faq.perl.org/ . The perlfaq-workers periodically post extracts of the latest perlfaq to comp.lang.perl.misc. -You can view the source tree at https://github.com/briandfoy/perlfaq -(which is outside of the main Perl source tree). The git repository -notes all changes to the FAQ and holds the latest version of the -working documents and may vary significantly from the version -distributed with the latest version of Perl. Check the repository -before sending your corrections. +The perlfaq documents are in the perl source tree (see +L<perlgit>). The git repository notes all changes to the FAQ and +holds the latest version of the working documents and may vary +significantly from the version distributed with the latest version of +Perl. Check the repository before sending your corrections. =head2 How to contribute to the perlfaq @@ -38,16 +37,13 @@ address to coordinate their efforts and track the perlfaq development. They appreciate your contributions to the FAQ but do not have time to provide individual help, so don't use this address to ask FAQs. -The perlfaq server posts extracts of the perlfaq to that newsgroup every -6 hours (or so), and the community of volunteers reviews and updates the -answers. If you'd like to help review and update the answers, check out -comp.lang.perl.misc. +The perlfaq server posts extracts of the perlfaq to that newsgroup +every 6 hours (or so), and the community of volunteers reviews and +updates the answers. If you'd like to help review and update the +answers, check out comp.lang.perl.misc. -You can also fork the git repository for the perlfaq and send a pull -request so the main repository can pull your changes. The repository -is at: - - https://github.com/briandfoy/perlfaq +You can also fork the perl repository, make your changes, and send them +to Perl 5 Porters. See L<perlgit>. =head2 What will happen if you mail your Perl programming problems to the authors? @@ -67,13 +63,13 @@ it, try the resources in L<perlfaq2>. Tom Christiansen wrote the original perlfaq then expanded it with the help of Nat Torkington. The perlfaq-workers maintain current document -and the dezinens of comp.lang.perl.misc regularly review and update the +and the denizens of comp.lang.perl.misc regularly review and update the FAQ. Several people have contributed answers, corrections, and comments, and the perlfaq notes those contributions wherever appropriate. =head1 AUTHOR AND COPYRIGHT -Tom Christainsen wrote the original version of this document. +Tom Christiansen wrote the original version of this document. brian d foy C<< <bdfoy@cpan.org> >> wrote this version. See the individual perlfaq documents for additional copyright information. @@ -121,7 +117,7 @@ What is Perl? =item * -Who supports Perl? Who develops it? Why is it free? +Who supports Perl? Who develops it? Why is it free? =item * @@ -311,7 +307,7 @@ Where can I get Perl macros for vi? =item * -Where can I get perl-mode for emacs? +Where can I get perl-mode or cperl-mode for emacs? =item * @@ -516,7 +512,7 @@ How do I capitalize all the words on one line? =item * -How can I split a [character] delimited string except when inside [character]? +How can I split a [character]-delimited string except when inside [character]? =item * @@ -676,6 +672,10 @@ How can I use a reference as a hash key? =item * +How can I check if a key exists in a multilevel hash? + +=item * + How do I handle binary data correctly? =item * @@ -801,11 +801,11 @@ Why can't I just open(FH, "E<gt>file.lock")? =item * -I still don't get locking. I just want to increment the number in the file. How can I do this? +I still don't get locking. I just want to increment the number in the file. How can I do this? =item * -All I want to do is append a small amount of text to the end of a file. Do I still have to use locking? +All I want to do is append a small amount of text to the end of a file. Do I still have to use locking? =item * @@ -898,7 +898,7 @@ How can I hope to use regular expressions without creating illegible and unmaint =item * -I'm having trouble matching over more than one line. What's wrong? +I'm having trouble matching over more than one line. What's wrong? =item * @@ -914,7 +914,7 @@ I put a regular expression into $/ but it didn't work. What's wrong? =item * -How do I substitute case insensitively on the LHS while preserving case on the RHS? +How do I substitute case-insensitively on the LHS while preserving case on the RHS? =item * @@ -934,7 +934,7 @@ What is C</o> really for? =item * -How do I use a regular expression to strip C style comments from a file? +How do I use a regular expression to strip C-style comments from a file? =item * @@ -942,7 +942,7 @@ Can I use Perl regular expressions to match balanced text? =item * -What does it mean that regexes are greedy? How can I get around it? +What does it mean that regexes are greedy? How can I get around it? =item * @@ -974,7 +974,7 @@ What good is C<\G> in a regular expression? =item * -Are Perl regexes DFAs or NFAs? Are they POSIX compliant? +Are Perl regexes DFAs or NFAs? Are they POSIX compliant? =item * @@ -1341,7 +1341,7 @@ What is the correct form of response from a CGI script? =item * -My CGI script runs from the command line but not the browser. (500 Server Error) +My CGI script runs from the command line but not the browser. (500 Server Error) =item * diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq1.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq1.pod index 16f58018049..ba70a822602 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq1.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq1.pod @@ -2,7 +2,7 @@ perlfaq1 - General Questions About Perl -=head1 DESCRIPTION +=head1 DESCRIPTION This section of the FAQ answers very general, high-level questions about Perl. @@ -61,7 +61,7 @@ users the informal support will more than suffice. See the answer to There is often a matter of opinion and taste, and there isn't any one answer that fits everyone. In general, you want to use either the current stable release, or the stable release immediately prior to that one. -Currently, those are perl5.10.x and perl5.8.x, respectively. +Currently, those are perl5.14.x and perl5.12.x, respectively. Beyond that, you have to consider several things and decide which is best for you. @@ -101,15 +101,17 @@ for a while, although not at the same level as the current releases. =item * -No one is actively supporting Perl 4. Five years ago it was a dead +No one is actively supporting Perl 4. Ten years ago it was a dead camel carcass (according to this document). Now it's barely a skeleton as its whitewashed bones have fractured or eroded. =item * There is no Perl 6 release scheduled, but it will be available when -it's ready. Stay tuned, but don't worry that you'll have to change -major versions of Perl; no one is going to take Perl 5 away from you. +it's ready. The joke is that it's scheduled for Christmas, but that we +just don't know which one. Stay tuned, but don't worry that you'll +have to change major versions of Perl; no one is going to take Perl 5 +away from you. =item * @@ -130,23 +132,24 @@ minor release (i.e. perl5.9.x, where 9 is the minor release). In short, Perl 4 is the past, Perl 5 is the present, and Perl 6 is the future. -The number after perl (i.e. the 5 after Perl 5) is the major release +The number after Perl (i.e. the 5 after Perl 5) is the major release of the perl interpreter as well as the version of the language. Each major version has significant differences that earlier versions cannot support. -The current major release of Perl is Perl 5, and was released in 1994. -It can run scripts from the previous major release, Perl 4 (March 1991), -but has significant differences. It introduced the concept of references, -complex data structures, and modules. The Perl 5 interpreter was a -complete re-write of the previous perl sources. +The current major release of Perl is Perl 5, and was first released in +1994. It can run scripts from the previous major release, Perl 4 +(March 1991), but has significant differences. It introduced the +concept of references, complex data structures, and modules. The Perl +5 interpreter was a complete re-write of the previous perl sources. -Perl 6 is the next major version of Perl, but it's still in development -in both its syntax and design. The work started in 2002 and is still -ongoing. Many of the most interesting features have shown up in the -latest versions of Perl 5, and some Perl 5 modules allow you to use some -Perl 6 syntax in your programs. You can learn more about Perl 6 at -http://dev.perl.org/perl6/ . +Perl 6 is the next major version of Perl, although it's not intended to +replace Perl 5. It's still in development in both its syntax and +design. The work started in 2002 and is still ongoing. Some of the +most interesting features have shown up in the latest versions of Perl +5, and some Perl 5 modules allow you to use some Perl 6 syntax in your +programs. The current leading implementation of Perl 6 is Rakudo ( +http://rakudo.org ). See L<perlhist> for a history of Perl revisions. @@ -367,7 +370,7 @@ might mean that Perl either saves them something (time, headaches, money) or gives them something (flexibility, power, testability). In general, the benefit of a language is closely related to the skill of -the people using that language. If you or your team can be more faster, +the people using that language. If you or your team can be faster, better, and stronger through Perl, you'll deliver more value. Remember, people often respond better to what they get out of it. If you run into resistance, figure out what those people get out of the other diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq2.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq2.pod index 036df5e9ab8..4e891a6865a 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq2.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq2.pod @@ -8,13 +8,13 @@ This section of the FAQ answers questions about where to find source and documentation for Perl, support, and related matters. -=head2 What machines support perl? Where do I get it? +=head2 What machines support perl? Where do I get it? The standard release of perl (the one maintained by the perl -development team) is distributed only in source code form. You +development team) is distributed only in source code form. You can find the latest releases at http://www.cpan.org/src/README.html . -Perl builds and runs on a bewildering number of platforms. Virtually +Perl builds and runs on a bewildering number of platforms. Virtually all known and current Unix derivatives are supported (perl's native platform), as are other systems like VMS, DOS, OS/2, Windows, QNX, BeOS, OS X, MPE/iX and the Amiga. @@ -23,7 +23,7 @@ Binary distributions for some proprietary platforms can be found http://www.cpan.org/ports/ directory. Because these are not part of the standard distribution, they may and in fact do differ from the base perl port in a variety of ways. You'll have to check their -respective release notes to see just what the differences are. These +respective release notes to see just what the differences are. These differences can be either positive (e.g. extensions for the features of the particular platform that are not supported in the source release of perl) or negative (e.g. might be based upon a less current @@ -52,10 +52,10 @@ IndigoPerl: Windows =head2 I don't have a C compiler. How can I build my own Perl interpreter? Since you don't have a C compiler, you're doomed and your vendor -should be sacrificed to the Sun gods. But that doesn't help you. +should be sacrificed to the Sun gods. But that doesn't help you. What you need to do is get a binary version of C<gcc> for your system -first. Consult the Usenet FAQs for your operating system for +first. Consult the Usenet FAQs for your operating system for information on where to get such a binary version. You might look around the net for a pre-built binary of Perl (or a @@ -73,7 +73,7 @@ applications, including compilers and Perl. That's probably because you forgot libraries, or library paths differ. You really should build the whole distribution on the machine it will -eventually live on, and then type C<make install>. Most other +eventually live on, and then type C<make install>. Most other approaches are doomed to failure. One simple way to check that things are in the right place is to print out @@ -83,7 +83,7 @@ the hard-coded C<@INC> that perl looks through for libraries: If this command lists any paths that don't exist on your system, then you may need to move the appropriate libraries to these locations, or create -symbolic links, aliases, or shortcuts appropriately. C<@INC> is also printed as +symbolic links, aliases, or shortcuts appropriately. C<@INC> is also printed as part of the output of % perl -V @@ -91,14 +91,14 @@ part of the output of You might also want to check out L<perlfaq8/"How do I keep my own module/library directory?">. -=head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? +=head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? Read the F<INSTALL> file, which is part of the source distribution. It describes in detail how to cope with most idiosyncrasies that the C<Configure> script can't work around for any given system or architecture. -=head2 What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? +=head2 What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? CPAN stands for Comprehensive Perl Archive Network, a multi-gigabyte archive replicated on hundreds of machines all over the world. CPAN @@ -108,7 +108,7 @@ commercial database interfaces to keyboard/screen control to web walking and CGI scripts. The master web site for CPAN is http://www.cpan.org/ and there is the CPAN Multiplexer at http://www.cpan.org/CPAN.html which will choose a mirror near you via -DNS. See http://www.perl.com/CPAN (without a slash at the end) for +DNS. See http://www.perl.com/CPAN (without a slash at the end) for how this process works. Also, http://mirror.cpan.org/ has a nice interface to the http://www.cpan.org/MIRRORED.BY mirror directory. @@ -117,7 +117,7 @@ to the most frequently asked questions about CPAN including how to become a mirror. C<CPAN/path/...> is a naming convention for files available on CPAN -sites. CPAN indicates the base directory of a CPAN mirror, and the +sites. CPAN indicates the base directory of a CPAN mirror, and the rest of the path is the path from that directory to the file. For instance, if you're using ftp://ftp.funet.fi/pub/languages/perl/CPAN as your CPAN site, the file C<CPAN/misc/japh> is downloadable as @@ -143,7 +143,7 @@ CPAN is a free service and is not affiliated with O'Reilly Media. =head2 Is there an ISO or ANSI certified version of Perl? -Certainly not. Larry expects that he'll be certified before Perl is. +Certainly not. Larry expects that he'll be certified before Perl is. =head2 Where can I get information on Perl? @@ -151,12 +151,12 @@ The complete Perl documentation is available with the Perl distribution. If you have Perl installed locally, you probably have the documentation installed as well: type C<man perl> if you're on a system resembling Unix. This will lead you to other important man pages, including how to set your -C<$MANPATH>. If you're not on a Unix system, access to the documentation -will be different; for example, documentation might only be in HTML format. All +C<$MANPATH>. If you're not on a Unix system, access to the documentation +will be different; for example, documentation might only be in HTML format. All proper perl installations have fully-accessible documentation. You might also try C<perldoc perl> in case your system doesn't -have a proper C<man> command, or it's been misinstalled. If that doesn't +have a proper C<man> command, or it's been misinstalled. If that doesn't work, try looking in C</usr/local/lib/perl5/pod> for documentation. If all else fails, consult http://perldoc.perl.org/ which has the @@ -165,18 +165,18 @@ complete documentation in HTML and PDF format. Many good books have been written about Perl--see the section later in L<perlfaq2> for more details. -Tutorial documents are included in current or upcoming Perl releases +Tutorial documents included in current or upcoming Perl releases include L<perltoot> for objects or L<perlboot> for a beginner's approach to objects, L<perlopentut> for file opening semantics, L<perlreftut> for managing references, L<perlretut> for regular expressions, L<perlthrtut> for threads, L<perldebtut> for debugging, -and L<perlxstut> for linking C and Perl together. There may be more -by the time you read this. These URLs might also be useful: +and L<perlxstut> for linking C and Perl together. There may be more +by the time you read this. These URLs might also be useful: http://perldoc.perl.org/ http://bookmarks.cpan.org/search.cgi?cat=Training%2FTutorials -=head2 What are the Perl newsgroups on Usenet? Where do I post questions? +=head2 What are the Perl newsgroups on Usenet? Where do I post questions? Several groups devoted to the Perl language are on Usenet: @@ -187,10 +187,10 @@ Several groups devoted to the Perl language are on Usenet: comp.lang.perl.tk Using Tk (and X) from Perl Some years ago, comp.lang.perl was divided into those groups, and -comp.lang.perl itself officially removed. While that group may still +comp.lang.perl itself officially removed. While that group may still be found on some news servers, it is unwise to use it, because postings there will not appear on news servers which honour the -official list of group names. Use comp.lang.perl.misc for topics +official list of group names. Use comp.lang.perl.misc for topics which do not have a more-appropriate specific group. There is also a Usenet gateway to Perl mailing lists sponsored by @@ -211,202 +211,26 @@ but asking someone to write your code for free is not very cool. =head2 Where should I post source code? You should post source code to whichever group is most appropriate, but -feel free to cross-post to comp.lang.perl.misc. If you want to cross-post +feel free to cross-post to comp.lang.perl.misc. If you want to cross-post to alt.sources, please make sure it follows their posting standards, including setting the Followup-To header line to NOT include alt.sources; see their FAQ ( http://www.faqs.org/faqs/alt-sources-intro/ ) for details. If you're just looking for software, first use Google ( http://www.google.com ), Google's Usenet search interface -( http://groups.google.com ), and CPAN Search ( http://search.cpan.org ). +( http://groups.google.com ), and CPAN Search ( http://search.cpan.org ). This is faster and more productive than just posting a request. =head2 Perl Books -A number of books on Perl and/or CGI programming are available. A few -of these are good, some are OK, but many aren't worth your money. -There is a list of these books, some with extensive reviews, at -http://books.perl.org/ . If you don't see your book listed here, you -can write to perlfaq-workers@perl.org . - -The incontestably definitive reference book on Perl, written by -the creator of Perl, is Programming Perl: - - Programming Perl (the "Camel Book"): - by Larry Wall, Tom Christiansen, and Jon Orwant - ISBN 0-596-00027-8 [3rd edition July 2000] - http://www.oreilly.com/catalog/pperl3/ - (English, translations to several languages are also available) - -The companion volume to the Camel containing thousands -of real-world examples, mini-tutorials, and complete programs is: - - The Perl Cookbook (the "Ram Book"): - by Tom Christiansen and Nathan Torkington, - with Foreword by Larry Wall - ISBN 0-596-00313-7 [2nd Edition August 2003] - http://www.oreilly.com/catalog/perlckbk2/ - -If you're already a seasoned programmer, then the Camel Book might -suffice for you to learn Perl. If you're not, check out the -Llama book: - - Learning Perl - by Randal L. Schwartz, Tom Phoenix, and brian d foy - ISBN 0-596-10105-8 [4th edition July 2005] - http://www.oreilly.com/catalog/learnperl4/ - -And for more advanced information on writing larger programs, -presented in the same style as the Llama book, continue your education -with the Alpaca book: - - Intermediate Perl (the "Alpaca Book") - by Randal L. Schwartz and brian d foy, with Tom Phoenix (foreword by Damian Conway) - ISBN 0-596-10206-2 [1st edition March 2006] - http://www.oreilly.com/catalog/lrnperlorm/ - -Addison-Wesley ( http://www.awlonline.com/ ) and Manning -( http://www.manning.com/ ) are also publishers of some fine Perl books -such as I<Object Oriented Programming with Perl> by Damian Conway and -I<Network Programming with Perl> by Lincoln Stein. - -An excellent technical book discounter is Bookpool at -http://www.bookpool.com/ where a 30% discount or more is not unusual. - -What follows is a list of the books that the FAQ authors found personally -useful. Your mileage may (but, we hope, probably won't) vary. - -Recommended books on (or mostly on) Perl follow. - -=over 4 - -=item References - - Programming Perl - by Larry Wall, Tom Christiansen, and Jon Orwant - ISBN 0-596-00027-8 [3rd edition July 2000] - http://www.oreilly.com/catalog/pperl3/ - - Perl 5 Pocket Reference - by Johan Vromans - ISBN 0-596-00374-9 [4th edition July 2002] - http://www.oreilly.com/catalog/perlpr4/ - -=item Tutorials - - Beginning Perl - by James Lee - ISBN 1-59059-391-X [2nd edition August 2004] - http://apress.com/book/bookDisplay.html?bID=344 - - Elements of Programming with Perl - by Andrew L. Johnson - ISBN 1-884777-80-5 [1st edition October 1999] - http://www.manning.com/johnson/ - - Learning Perl - by Randal L. Schwartz, Tom Phoenix, and brian d foy - ISBN 0-596-52010-7 [5th edition June 2008] - http://oreilly.com/catalog/9780596520106/ - - Intermediate Perl (the "Alpaca Book") - by Randal L. Schwartz and brian d foy, with Tom Phoenix (foreword by Damian Conway) - ISBN 0-596-10206-2 [1st edition March 2006] - http://www.oreilly.com/catalog/intermediateperl/ - - Mastering Perl - by brian d foy - ISBN 0-596-52724-1 [1st edition July 2007] - http://www.oreilly.com/catalog/9780596527242/ - -=item Task-Oriented - - Writing Perl Modules for CPAN - by Sam Tregar - ISBN 1-59059-018-X [1st edition August 2002] - http://apress.com/book/bookDisplay.html?bID=14 - - The Perl Cookbook - by Tom Christiansen and Nathan Torkington - with foreword by Larry Wall - ISBN 1-56592-243-3 [1st edition August 1998] - http://www.oreilly.com/catalog/cookbook/ - - Effective Perl Programming - by Joseph Hall - ISBN 0-201-41975-0 [1st edition 1998] - http://www.awl.com/ - - Real World SQL Server Administration with Perl - by Linchi Shea - ISBN 1-59059-097-X [1st edition July 2003] - http://apress.com/book/bookDisplay.html?bID=171 - -=item Special Topics - - Perl Best Practices - by Damian Conway - ISBN: 0-596-00173-8 [1st edition July 2005] - http://www.oreilly.com/catalog/perlbp/ - - Higher Order Perl - by Mark-Jason Dominus - ISBN: 1558607013 [1st edition March 2005] - http://hop.perl.plover.com/ - - Perl 6 Now: The Core Ideas Illustrated with Perl 5 - by Scott Walters - ISBN 1-59059-395-2 [1st edition December 2004] - http://apress.com/book/bookDisplay.html?bID=355 - - Mastering Regular Expressions - by Jeffrey E. F. Friedl - ISBN 0-596-00289-0 [2nd edition July 2002] - http://www.oreilly.com/catalog/regex2/ - - Network Programming with Perl - by Lincoln Stein - ISBN 0-201-61571-1 [1st edition 2001] - http://www.awlonline.com/ - - Object Oriented Perl - by Damian Conway - with foreword by Randal L. Schwartz - ISBN 1-884777-79-1 [1st edition August 1999] - http://www.manning.com/conway/ - - Data Munging with Perl - by Dave Cross - ISBN 1-930110-00-6 [1st edition 2001] - http://www.manning.com/cross - - Mastering Perl/Tk - by Steve Lidie and Nancy Walsh - ISBN 1-56592-716-8 [1st edition January 2002] - http://www.oreilly.com/catalog/mastperltk/ - - Extending and Embedding Perl - by Tim Jenness and Simon Cozens - ISBN 1-930110-82-0 [1st edition August 2002] - http://www.manning.com/jenness - - Perl Debugger Pocket Reference - by Richard Foley - ISBN 0-596-00503-2 [1st edition January 2004] - http://www.oreilly.com/catalog/perldebugpr/ - - Pro Perl Debugging - by Richard Foley with Andy Lester - ISBN 1-59059-454-1 [1st edition July 2005] - http://www.apress.com/book/view/1590594541 - -=back +There are many good books on Perl. See the L<perlbook> documentation or +( http://books.perl.org ). =head2 Which magazines have Perl content? I<The Perl Review> ( http://www.theperlreview.com ) focuses on Perl almost completely (although it sometimes sneaks in an article about -another language). There's also I<$foo Magazin>, a german magazine +another language). There's also I<$foo Magazin>, a German magazine dedicated to Perl, at ( http://www.foo-magazin.de ). The I<Perl-Zeitung> is a German-speaking magazine for Perl beginners @@ -425,22 +249,23 @@ http://www.stonehenge.com/merlyn/LinuxMag/ . The first (and for a long time, only) periodical devoted to All Things Perl, I<The Perl Journal> contains tutorials, demonstrations, case -studies, announcements, contests, and much more. I<TPJ> has columns +studies, announcements, contests, and much more. I<TPJ> has columns on web development, databases, Win32 Perl, graphical programming, regular expressions, and networking, and sponsors the Obfuscated Perl -Contest and the Perl Poetry Contests. Beginning in November 2002, I<TPJ> +Contest and the Perl Poetry Contests. Beginning in November 2002, I<TPJ> moved to a reader-supported monthly e-zine format in which subscribers can download issues as PDF documents. In 2006, I<TPJ> merged with Dr. Dobbs Journal (online edition). To read old I<TPJ> articles, see -http://www.ddj.com/ . +http://www.ddj.com/ or brian d foy's index of online TPJ content +( http://www.perlmonks.org/index.pl?node_id=711609 ). =head2 What mailing lists are there for Perl? Most of the major modules (C<Tk>, C<CGI>, C<libwww-perl>) have their own -mailing lists. Consult the documentation that came with the module for +mailing lists. Consult the documentation that came with the module for subscription information. -A comprehensive list of Perl related mailing lists can be found at: +A comprehensive list of Perl-related mailing lists can be found at: http://lists.perl.org/ @@ -461,9 +286,9 @@ seek. In a real sense, perl already I<is> commercial software: it has a license that you can grab and carefully read to your manager. It is distributed in releases and comes in well-defined packages. There is a very large -user community and an extensive literature. The comp.lang.perl.* +user community and an extensive literature. The comp.lang.perl.* newsgroups and several of the mailing lists provide free answers to your -questions in near real-time. Perl has traditionally been supported by +questions in near real-time. Perl has traditionally been supported by Larry, scores of software designers and developers, and myriad programmers, all working for free to create a useful thing to make life better for everyone. @@ -472,7 +297,7 @@ However, these answers may not suffice for managers who require a purchase order from a company whom they can sue should anything go awry. Or maybe they need very serious hand-holding and contractual obligations. Shrink-wrapped CDs with perl on them are available from several sources if -that will help. For example, many Perl books include a distribution of perl, +that will help. For example, many Perl books include a distribution of perl, as do the O'Reilly Perl Resource Kits (in both the Unix flavor and in the proprietary Microsoft flavor); the free Unix distributions also all come with perl. @@ -486,7 +311,7 @@ found an actual bug. If you've found a bug with the perl interpreter or one of the modules in the standard library (those that come with Perl), you can use the -C<perlbug> utility that comes with Perl (>= 5.004). It collects +L<perlbug> utility that comes with Perl (>= 5.004). It collects information about your installation to include with your message, then sends the message to the right place. @@ -510,30 +335,32 @@ module documentation too. =head2 What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org? -Perl.com at http://www.perl.com/ is part of the O'Reilly Network, a -subsidiary of O'Reilly Media. +Perl.com ( http://www.perl.com/ ) used to be part of the O'Reilly +Network, a subsidiary of O'Reilly Media. Although it retains most of +the original content from its O'Reilly Network, it is now hosted by +The Perl Foundation. The Perl Foundation is an advocacy organization for the Perl language -which maintains the web site http://www.perl.org/ as a general +which maintains the web site ( http://www.perl.org/ ) as a general advocacy site for the Perl language. It uses the domain to provide general support services to the Perl community, including the hosting -of mailing lists, web sites, and other services. There are also many -other sub-domains for special topics like learning Perl, Perl news, jobs -in Perl, such as: +of mailing lists, web sites, and other services. There are also many +other sub-domains for special topics like learning Perl, Perl news, +jobs in Perl, such as: + http://www.perl.org/ http://learn.perl.org/ - http://use.perl.org/ http://jobs.perl.org/ http://lists.perl.org/ Perl Mongers uses the pm.org domain for services related to Perl user -groups, including the hosting of mailing lists and web sites. See the -Perl user group web site at http://www.pm.org/ for more information about +groups, including the hosting of mailing lists and web sites. See the +Perl Mongers website ( http://www.pm.org/ ) for more information about joining, starting, or requesting services for a Perl user group. -http://www.cpan.org/ is the Comprehensive Perl Archive Network, -a replicated worldwide repository of Perl software, see -the I<What is CPAN?> question earlier in this document. +CPAN, or the Comprehensive Perl Archive Network ( +http://www.cpan.org/ ), is a replicated, worldwide repository of Perl +software. See I<What is CPAN?> in L<perlfaq2>. =head1 AUTHOR AND COPYRIGHT @@ -544,7 +371,7 @@ This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. Irrespective of its distribution, all code examples here are in the public -domain. You are permitted and encouraged to use this code and any +domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you -see fit. A simple comment in the code giving credit to the FAQ would +see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required. diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq3.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq3.pod index e2fe11621ba..3093d36afa7 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq3.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq3.pod @@ -44,7 +44,7 @@ operations typically found in symbolic debuggers. The C<psh> (Perl sh) is currently at version 1.8. The Perl Shell is a shell that combines the interactive nature of a Unix shell with the power of -Perl. The goal is a full featured shell that behaves as expected for +Perl. The goal is a full-featured shell that behaves as expected for normal shell activity and uses Perl syntax and functionality for control-flow statements and other things. You can get C<psh> at http://sourceforge.net/projects/psh/ . @@ -113,7 +113,7 @@ with C<File::Find> which is part of the standard library: print join "\n", @files; -If you simply need to quickly check to see if a module is +If you simply need to check quickly to see if a module is available, you can check for its documentation. If you can read the documentation the module is most likely installed. If you cannot read the documentation, the module might not @@ -243,7 +243,7 @@ as you write it will help prevent bugs. Your editor can and should help you with this. The perl-mode or newer cperl-mode for emacs can provide remarkable amounts of help with most (but not all) code, and even less programmable editors can provide significant -assistance. Tom Christiansen and many other VI users swear by +assistance. Tom Christiansen and many other VI users swear by the following settings in vi and its clones: set ai sw=4 @@ -267,7 +267,7 @@ Ctags uses an index to quickly find things in source code, and many popular editors support ctags for several different languages, including Perl. -Exuberent ctags supports Perl: http://ctags.sourceforge.net/ +Exuberant ctags supports Perl: http://ctags.sourceforge.net/ You might also try pltags: http://www.mscha.com/pltags.zip @@ -324,7 +324,7 @@ under Windows 95/98/NT/2000. http://www.optiperl.com/ OptiPerl is a Windows IDE with simulated CGI environment, including -debugger and syntax highlighting editor. +debugger and syntax-highlighting editor. =item Padre @@ -357,7 +357,7 @@ Visual Perl is a Visual Studio.NET plug-in from ActiveState. http://www.zeusedit.com/lookmain.html Zeus for Window is another Win32 multi-language editor/IDE -that comes with support for Perl: +that comes with support for Perl. =back @@ -455,7 +455,7 @@ http://www.contexteditor.org/ There is also a toyedit Text widget based editor written in Perl that is distributed with the Tk module on CPAN. The ptkdb -( http://ptkdb.sourceforge.net/ ) is a Perl/tk based debugger that +( http://ptkdb.sourceforge.net/ ) is a Perl/Tk-based debugger that acts as a development environment of sorts. Perl Composer ( http://perlcomposer.sourceforge.net/ ) is an IDE for Perl/Tk GUI creation. @@ -510,7 +510,7 @@ is a full Perl development environment with full debugger support =item Alpha is an editor, written and extensible in Tcl, that nonetheless has -built in support for several popular markup and programming languages +built-in support for several popular markup and programming languages, including Perl and HTML ( http://www.his.com/~jguyer/Alpha/Alpha8.html ). =item BBEdit and BBEdit Lite @@ -583,7 +583,7 @@ These are Perl bindings for the Gtk toolkit ( http://www.gtk.org ). The interface changed significantly between versions 1 and 2 so they have separate Perl modules. It runs under Unix, Win32 and Mac OS X (currently it requires an X server on Mac OS, but a 'native' port is underway), and -the widgets look the same on every plaform: i.e., they don't match the +the widgets look the same on every platform: i.e., they don't match the native widgets. As with Wx, the Perl bindings follow the C API closely, and the documentation requires you to read the C documentation to understand it. @@ -761,7 +761,7 @@ requires some judgement, however, because any changes will be propagated back to the original data. If you really want to mangle (er, modify) a copy, you'll have to sacrifice the memory needed to make one. -=item * Tie large variables to disk. +=item * Tie large variables to disk For "big" data stores (i.e. ones that exceed available memory) consider using one of the DB modules to store it on disk instead of in RAM. This @@ -840,7 +840,8 @@ Both of these solutions can have far-reaching effects on your system and on the way you write your CGI programs, so investigate them with care. -See http://www.cpan.org/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . +See also +http://www.cpan.org/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . =head2 How can I hide the source for my Perl program? diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq4.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq4.pod index 45cc9e044dd..eb18743f822 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq4.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq4.pod @@ -13,7 +13,7 @@ numbers, dates, strings, arrays, hashes, and miscellaneous data issues. For the long explanation, see David Goldberg's "What Every Computer Scientist Should Know About Floating-Point Arithmetic" -(http://docs.sun.com/source/806-3568/ncg_goldberg.html). +(L<http://web.cse.msu.edu/~cse320/Documents/FloatingPoint.pdf>). Internally, your computer represents floating-point numbers in binary. Digital (as in powers of two) computers cannot store all numbers @@ -25,8 +25,8 @@ L<perlnumber> shows the gory details of number representations and conversions. To limit the number of decimal places in your numbers, you can use the -C<printf> or C<sprintf> function. See the L<"Floating Point -Arithmetic"|perlop> for more details. +C<printf> or C<sprintf> function. See +L<perlop/"Floating Point Arithmetic"> for more details. printf "%.2f", 10/3; @@ -117,8 +117,8 @@ the real axis into the complex plane, for example the inverse sine of Rounding in financial applications can have serious implications, and the rounding method used should be specified precisely. In these -cases, it probably pays not to trust whichever system rounding is -being used by Perl, but to instead implement the rounding function you +cases, it probably pays not to trust whichever system of rounding is +being used by Perl, but instead to implement the rounding function you need yourself. To see why, notice how you'll still have an issue on half-way-point @@ -131,7 +131,7 @@ alternation: Don't blame Perl. It's the same as in C. IEEE says we have to do this. Perl numbers whose absolute values are integers under 2**31 (on -32 bit machines) will work pretty much like mathematical integers. +32-bit machines) will work pretty much like mathematical integers. Other numbers are not guaranteed. =head2 How do I convert between numeric representations/bases/radixes? @@ -143,7 +143,7 @@ exhaustive. Some of the examples later in L<perlfaq4> use the C<Bit::Vector> module from CPAN. The reason you might choose C<Bit::Vector> over the -perl built in functions is that it works with numbers of ANY size, +perl built-in functions is that it works with numbers of ANY size, that it is optimized for speed on some operations, and for at least some programmers the notation might be familiar. @@ -244,7 +244,7 @@ Using C<pack> and C<unpack> for larger strings: substr("0" x 32 . "11110101011011011111011101111", -32))); $dec = sprintf("%d", $int); - # substr() is used to left pad a 32 character string with zeros. + # substr() is used to left-pad a 32-character string with zeros. Using C<Bit::Vector>: @@ -285,7 +285,9 @@ C<3>). Saying C<"11" & "3"> performs the "and" operation on strings (yielding C<"1">). Most problems with C<&> and C<|> arise because the programmer thinks -they have a number but really it's a string. The rest arise because +they have a number but really it's a string or vice versa. To avoid this, +stringify the arguments explicitly (using C<""> or C<qq()>) or convert them +to numbers explicitly (using C<0+$arg>). The rest arise because the programmer says: if ("\020\020" & "\101\101") { @@ -326,12 +328,12 @@ To call a function on each integer in a (small) range, you B<can> use: @results = map { some_func($_) } (5 .. 25); -but you should be aware that the C<..> operator creates an array of +but you should be aware that the C<..> operator creates a list of all integers in the range. This can take a lot of memory for large ranges. Instead use: @results = (); - for ($i=5; $i < 500_005; $i++) { + for ($i=5; $i <= 500_005; $i++) { push(@results, some_func($i)); } @@ -360,7 +362,7 @@ call C<srand> more than once--you make your numbers less random, rather than more. Computers are good at being predictable and bad at being random -(despite appearances caused by bugs in your programs :-). see the +(despite appearances caused by bugs in your programs :-). The F<random> article in the "Far More Than You Ever Wanted To Know" collection in L<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz>, courtesy of Tom Phoenix, talks more about this. John von Neumann said, "Anyone @@ -405,10 +407,11 @@ integers (inclusive), For example: C<random_int_between(50,120)>. =head2 How do I find the day or week of the year? -The C<localtime> function returns the day of the year. Without an +The day of the year is in the list returned +by the C<localtime> function. Without an argument C<localtime> uses the current time. - $day_of_year = (localtime)[7]; + my $day_of_year = (localtime)[7]; The C<POSIX> module can also format a date as the day of the year or week of the year. @@ -424,7 +427,14 @@ a time in epoch seconds for the argument to C<localtime>. my $week_of_year = strftime "%W", localtime( mktime( 0, 0, 0, 18, 11, 87 ) ); -The C<Date::Calc> module provides two functions to calculate these. +You can also use C<Time::Piece>, which comes with Perl and provides a +C<localtime> that returns an object: + + use Time::Piece; + my $day_of_year = localtime->yday; + my $week_of_year = localtime->week; + +The C<Date::Calc> module provides two functions to calculate these, too: use Date::Calc; my $day_of_year = Day_of_Year( 1987, 12, 18 ); @@ -446,7 +456,7 @@ On some systems, the C<POSIX> module's C<strftime()> function has been extended in a non-standard way to use a C<%C> format, which they sometimes claim is the "century". It isn't, because on most such systems, this is only the first two digits of the four-digit year, and -thus cannot be used to reliably determine the current century or +thus cannot be used to determine reliably the current century or millennium. =head2 How can I compare two dates and find the difference? @@ -454,43 +464,74 @@ millennium. (contributed by brian d foy) You could just store all your dates as a number and then subtract. -Life isn't always that simple though. If you want to work with -formatted dates, the C<Date::Manip>, C<Date::Calc>, or C<DateTime> -modules can help you. +Life isn't always that simple though. + +The C<Time::Piece> module, which comes with Perl, replaces C<localtime> +with a version that returns an object. It also overloads the comparison +operators so you can compare them directly: + + use Time::Piece; + my $date1 = localtime( $some_time ); + my $date2 = localtime( $some_other_time ); + + if( $date1 < $date2 ) { + print "The date was in the past\n"; + } + +You can also get differences with a subtraction, which returns a +C<Time::Seconds> object: + + my $diff = $date1 - $date2; + print "The difference is ", $date_diff->days, " days\n"; + +If you want to work with formatted dates, the C<Date::Manip>, +C<Date::Calc>, or C<DateTime> modules can help you. =head2 How can I take a string and turn it into epoch seconds? If it's a regular enough string that it always has the same format, you can split it up and pass the parts to C<timelocal> in the standard -C<Time::Local> module. Otherwise, you should look into the C<Date::Calc> -and C<Date::Manip> modules from CPAN. +C<Time::Local> module. Otherwise, you should look into the C<Date::Calc>, +C<Date::Parse>, and C<Date::Manip> modules from CPAN. =head2 How can I find the Julian Day? (contributed by brian d foy and Dave Cross) -You can use the C<Time::JulianDay> module available on CPAN. Ensure -that you really want to find a Julian day, though, as many people have -different ideas about Julian days. See -http://www.hermetic.ch/cal_stud/jdn.htm for instance. +You can use the C<Time::Piece> module, part of the Standard Library, +which can convert a date/time to a Julian Day: -You can also try the C<DateTime> module, which can convert a date/time -to a Julian Day. + $ perl -MTime::Piece -le 'print localtime->julian_day' + 2455607.7959375 - $ perl -MDateTime -le'print DateTime->today->jd' - 2453401.5 +Or the modified Julian Day: -Or the modified Julian Day - - $ perl -MDateTime -le'print DateTime->today->mjd' - 53401 + $ perl -MTime::Piece -le 'print localtime->mjd' + 55607.2961226851 Or even the day of the year (which is what some people think of as a -Julian day) +Julian day): + + $ perl -MTime::Piece -le 'print localtime->yday' + 45 + +You can also do the same things with the C<DateTime> module: + $ perl -MDateTime -le'print DateTime->today->jd' + 2453401.5 + $ perl -MDateTime -le'print DateTime->today->mjd' + 53401 $ perl -MDateTime -le'print DateTime->today->doy' 31 +You can use the C<Time::JulianDay> module available on CPAN. Ensure +that you really want to find a Julian day, though, as many people have +different ideas about Julian days (see http://www.hermetic.ch/cal_stud/jdn.htm +for instance): + + $ perl -MTime::JulianDay -le 'print local_julian_day( time )' + 55608 + =head2 How do I find yesterday's date? X<date> X<yesterday> X<DateTime> X<Date::Calc> X<Time::Local> X<daylight saving time> X<day> X<Today_and_Now> X<localtime> @@ -498,8 +539,10 @@ X<timelocal> (contributed by brian d foy) -Use one of the Date modules. The C<DateTime> module makes it simple, and -give you the same time of day, only the day before. +To do it correctly, you can use one of the C<Date> modules since they +work with calendars instead of times. The C<DateTime> module makes it +simple, and give you the same time of day, only the day before, +despite daylight saving time changes: use DateTime; @@ -519,24 +562,35 @@ function. Most people try to use the time rather than the calendar to figure out dates, but that assumes that days are twenty-four hours each. For most people, there are two days a year when they aren't: the switch to -and from summer time throws this off. Let the modules do the work. +and from summer time throws this off. For example, the rest of the +suggestions will be wrong sometimes: + +Starting with Perl 5.10, C<Time::Piece> and C<Time::Seconds> are part +of the standard distribution, so you might think that you could do +something like this: + + use Time::Piece; + use Time::Seconds; + + my $yesterday = localtime() - ONE_DAY; # WRONG + print "Yesterday was $yesterday\n"; -If you absolutely must do it yourself (or can't use one of the -modules), here's a solution using C<Time::Local>, which comes with -Perl: +The C<Time::Piece> module exports a new C<localtime> that returns an +object, and C<Time::Seconds> exports the C<ONE_DAY> constant that is a +set number of seconds. This means that it always gives the time 24 +hours ago, which is not always yesterday. This can cause problems +around the end of daylight saving time when there's one day that is 25 +hours long. + +You have the same problem with C<Time::Local>, which will give the wrong +answer for those same special cases: # contributed by Gunnar Hjalmarsson use Time::Local; my $today = timelocal 0, 0, 12, ( localtime )[3..5]; - my ($d, $m, $y) = ( localtime $today-86400 )[3..5]; + my ($d, $m, $y) = ( localtime $today-86400 )[3..5]; # WRONG printf "Yesterday: %d-%02d-%02d\n", $y+1900, $m+1, $d; -In this case, you measure the day starting at noon, and subtract 24 -hours. Even if the length of the calendar day is 23 or 25 hours, -you'll still end up on the previous calendar day, although not at -noon. Since you don't care about the time, the one hour difference -doesn't matter and you end up with the previous date. - =head2 Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant? (contributed by brian d foy) @@ -545,21 +599,21 @@ Perl itself never had a Y2K problem, although that never stopped people from creating Y2K problems on their own. See the documentation for C<localtime> for its proper use. -Starting with Perl 5.11, C<localtime> and C<gmtime> can handle dates past +Starting with Perl 5.12, C<localtime> and C<gmtime> can handle dates past 03:14:08 January 19, 2038, when a 32-bit based time would overflow. You still might get a warning on a 32-bit C<perl>: - % perl5.11.2 -E 'say scalar localtime( 0x9FFF_FFFFFFFF )' + % perl5.12 -E 'say scalar localtime( 0x9FFF_FFFFFFFF )' Integer overflow in hexadecimal number at -e line 1. Wed Nov 1 19:42:39 5576711 On a 64-bit C<perl>, you can get even larger dates for those really long running projects: - % perl5.11.2 -E 'say scalar gmtime( 0x9FFF_FFFFFFFF )' + % perl5.12 -E 'say scalar gmtime( 0x9FFF_FFFFFFFF )' Thu Nov 2 00:42:39 5576711 -You're still out of luck if you need to keep tracking of decaying protons +You're still out of luck if you need to keep track of decaying protons though. =head1 Data: Strings @@ -594,11 +648,11 @@ This won't expand C<"\n"> or C<"\t"> or any other special escapes. You can use the substitution operator to find pairs of characters (or runs of characters) and replace them with a single instance. In this substitution, we find a character in C<(.)>. The memory parentheses -store the matched character in the back-reference C<\1> and we use +store the matched character in the back-reference C<\g1> and we use that to require that the same thing immediately follow it. We replace that part of the string with the character in C<$1>. - s/(.)\1/$1/g; + s/(.)\g1/$1/g; We can also use the transliteration operator, C<tr///>. In this example, the search list side of our C<tr///> contains nothing, but @@ -849,7 +903,7 @@ that C<s> after the apostrophe? You could try a regular expression: Now, what if you don't want to capitalize that "and"? Just use L<Text::Autoformat> and get on with the next problem. :) -=head2 How can I split a [character] delimited string except when inside [character]? +=head2 How can I split a [character]-delimited string except when inside [character]? Several modules can handle this sort of parsing--C<Text::Balanced>, C<Text::CSV>, C<Text::CSV_XS>, and C<Text::ParseWords>, among others. @@ -890,14 +944,14 @@ Perl distribution) lets you say: A substitution can do this for you. For a single line, you want to replace all the leading or trailing whitespace with nothing. You -can do that with a pair of substitutions. +can do that with a pair of substitutions: s/^\s+//; s/\s+$//; You can also write that as a single substitution, although it turns out the combined statement is slower than the separate ones. That -might not matter to you, though. +might not matter to you, though: s/^\s+|\s+$//g; @@ -906,30 +960,29 @@ beginning or the end of the string since the anchors have a lower precedence than the alternation. With the C</g> flag, the substitution makes all possible matches, so it gets both. Remember, the trailing newline matches the C<\s+>, and the C<$> anchor can match to the -physical end of the string, so the newline disappears too. Just add +absolute end of the string, so the newline disappears too. Just add the newline to the output, which has the added benefit of preserving "blank" (consisting entirely of whitespace) lines which the C<^\s+> -would remove all by itself. +would remove all by itself: - while( <> ) - { + while( <> ) { s/^\s+|\s+$//g; print "$_\n"; } -For a multi-line string, you can apply the regular expression -to each logical line in the string by adding the C</m> flag (for +For a multi-line string, you can apply the regular expression to each +logical line in the string by adding the C</m> flag (for "multi-line"). With the C</m> flag, the C<$> matches I<before> an -embedded newline, so it doesn't remove it. It still removes the -newline at the end of the string. +embedded newline, so it doesn't remove it. This pattern still removes +the newline at the end of the string: $string =~ s/^\s+|\s+$//gm; Remember that lines consisting entirely of whitespace will disappear, since the first part of the alternation can match the entire string -and replace it with nothing. If need to keep embedded blank lines, +and replace it with nothing. If you need to keep embedded blank lines, you have to do a little more work. Instead of matching any whitespace -(since that includes a newline), just match the other whitespace. +(since that includes a newline), just match the other whitespace: $string =~ s/^[\t\f ]+|[\t\f ]+$//mg; @@ -1119,16 +1172,18 @@ Stringification also destroys arrays. =head2 Why don't my E<lt>E<lt>HERE documents work? -Check for these three things: +Here documents are found in L<perlop>. Check for these three things: =over 4 =item There must be no space after the E<lt>E<lt> part. -=item There (probably) should be a semicolon at the end. +=item There (probably) should be a semicolon at the end of the opening token =item You can't (easily) have any space in front of the tag. +=item There needs to be at least a line separator after the end token. + =back If you want to indent the text in the here document, you @@ -1162,7 +1217,7 @@ subsequent line. sub fix { local $_ = shift; my ($white, $leader); # common whitespace and common leading string - if (/^\s*(?:([^\w\s]+)(\s*).*\n)(?:\s*\1\2?.*\n)+$/) { + if (/^\s*(?:([^\w\s]+)(\s*).*\n)(?:\s*\g1\g2?.*\n)+$/) { ($white, $leader) = ($2, quotemeta($1)); } else { ($white, $leader) = (/^(\s+)/, ''); @@ -1222,7 +1277,7 @@ for list operations, so list operations also work on arrays: wash_animals( qw( dog cat bird ) ); wash_animals( @animals ); -Array operations, which change the scalars, reaaranges them, or adds +Array operations, which change the scalars, rearranges them, or adds or subtracts some scalars, only work on arrays. These can't work on a list, which is fixed. Array operations include C<shift>, C<unshift>, C<push>, C<pop>, and C<splice>. @@ -1269,7 +1324,7 @@ context. The comma operator (yes, it's an operator!) in scalar context evaluates its lefthand side, throws away the result, and evaluates it's righthand side and returns the result. In effect, that list-lookalike assigns to C<$scalar> it's rightmost value. Many -people mess this up becuase they choose a list-lookalike whose +people mess this up because they choose a list-lookalike whose last element is also the count they expect: my $scalar = ( 1, 2, 3 ); # $scalar gets 3, accidentally @@ -1562,53 +1617,23 @@ that satisfies the condition. =head2 How do I handle linked lists? -In general, you usually don't need a linked list in Perl, since with -regular arrays, you can push and pop or shift and unshift at either -end, or you can use splice to add and/or remove arbitrary number of -elements at arbitrary points. Both pop and shift are O(1) -operations on Perl's dynamic arrays. In the absence of shifts and -pops, push in general needs to reallocate on the order every log(N) -times, and unshift will need to copy pointers each time. - -If you really, really wanted, you could use structures as described in -L<perldsc> or L<perltoot> and do just what the algorithm book tells -you to do. For example, imagine a list node like this: - - $node = { - VALUE => 42, - LINK => undef, - }; - -You could walk the list this way: +(contributed by brian d foy) - print "List: "; - for ($node = $head; $node; $node = $node->{LINK}) { - print $node->{VALUE}, " "; - } - print "\n"; +Perl's arrays do not have a fixed size, so you don't need linked lists +if you just want to add or remove items. You can use array operations +such as C<push>, C<pop>, C<shift>, C<unshift>, or C<splice> to do +that. -You could add to the list this way: +Sometimes, however, linked lists can be useful in situations where you +want to "shard" an array so you have have many small arrays instead of +a single big array. You can keep arrays longer than Perl's largest +array index, lock smaller arrays separately in threaded programs, +reallocate less memory, or quickly insert elements in the middle of +the chain. - my ($head, $tail); - $tail = append($head, 1); # grow a new head - for $value ( 2 .. 10 ) { - $tail = append($tail, $value); - } - - sub append { - my($list, $value) = @_; - my $node = { VALUE => $value }; - if ($list) { - $node->{LINK} = $list->{LINK}; - $list->{LINK} = $node; - } - else { - $_[0] = $node; # replace caller's version - } - return $node; - } - -But again, Perl's built-in are virtually always good enough. +Steve Lembark goes through the details in his YAPC::NA 2009 talk "Perly +Linked Lists" ( http://www.slideshare.net/lembark/perly-linked-lists ), +although you can just use his C<LinkedList::Single> module. =head2 How do I handle circular lists? X<circular> X<array> X<Tie::Cycle> X<Array::Iterator::Circular> @@ -1745,7 +1770,7 @@ Or, simply: my $element = $array[ rand @array ]; =head2 How do I permute N elements of a list? -X<List::Permuter> X<permute> X<Algorithm::Loops> X<Knuth> +X<List::Permutor> X<permute> X<Algorithm::Loops> X<Knuth> X<The Art of Computer Programming> X<Fischer-Krause> Use the C<List::Permutor> module on CPAN. If the list is actually an @@ -2212,7 +2237,7 @@ You can look into using the C<DB_File> module and C<tie()> using the C<$DB_BTREE> hash bindings as documented in L<DB_File/"In Memory Databases">. The C<Tie::IxHash> module from CPAN might also be instructive. Although this does keep your hash sorted, you might not -like the slow down you suffer from the tie interface. Are you sure you +like the slowdown you suffer from the tie interface. Are you sure you need to do this? :) =head2 What's the difference between "delete" and "undef" with hashes? @@ -2347,7 +2372,8 @@ Or if you really want to save space: Either stringify the structure yourself (no fun), or else get the MLDBM (which uses Data::Dumper) module from CPAN and layer -it on top of either DB_File or GDBM_File. +it on top of either DB_File or GDBM_File. You might also try DBM::Deep, but +it can be a bit slow. =head2 How can I make my hash remember the order I put elements into it? @@ -2418,7 +2444,7 @@ Usually a hash ref, perhaps like this: PALS => [ "Norbert", "Rhys", "Phineas"], }; -References are documented in L<perlref> and the upcoming L<perlreftut>. +References are documented in L<perlref> and L<perlreftut>. Examples of complex data structures are given in L<perldsc> and L<perllol>. Examples of structures and object-oriented classes are in L<perltoot>. @@ -2451,11 +2477,79 @@ If you actually need to be able to get a real reference back from each hash entry, you can use the Tie::RefHash module, which does the required work for you. +=head2 How can I check if a key exists in a multilevel hash? + +(contributed by brian d foy) + +The trick to this problem is avoiding accidental autovivification. If +you want to check three keys deep, you might naïvely try this: + + my %hash; + if( exists $hash{key1}{key2}{key3} ) { + ...; + } + +Even though you started with a completely empty hash, after that call to +C<exists> you've created the structure you needed to check for C<key3>: + + %hash = ( + 'key1' => { + 'key2' => {} + } + ); + +That's autovivification. You can get around this in a few ways. The +easiest way is to just turn it off. The lexical C<autovivification> +pragma is available on CPAN. Now you don't add to the hash: + + { + no autovivification; + my %hash; + if( exists $hash{key1}{key2}{key3} ) { + ...; + } + } + +The C<Data::Diver> module on CPAN can do it for you too. Its C<Dive> +subroutine can tell you not only if the keys exist but also get the +value: + + use Data::Diver qw(Dive); + + my @exists = Dive( \%hash, qw(key1 key2 key3) ); + if( ! @exists ) { + ...; # keys do not exist + } + elsif( ! defined $exists[0] ) { + ...; # keys exist but value is undef + } + +You can easily do this yourself too by checking each level of the hash +before you move onto the next level. This is essentially what +C<Data::Diver> does for you: + + if( check_hash( \%hash, qw(key1 key2 key3) ) ) { + ...; + } + + sub check_hash { + my( $hash, @keys ) = @_; + + return unless @keys; + + foreach my $key ( @keys ) { + return unless eval { exists $hash->{$key} }; + $hash = $hash->{$key}; + } + + return 1; + } + =head1 Data: Misc =head2 How do I handle binary data correctly? -Perl is binary clean, so it can handle binary data just fine. +Perl is binary-clean, so it can handle binary data just fine. On Windows or DOS, however, you have to use C<binmode> for binary files to avoid conversions for line endings. In general, you should use C<binmode> any time you want to work with binary data. @@ -2469,31 +2563,40 @@ some gotchas. See the section on Regular Expressions. =head2 How do I determine whether a scalar is a number/whole/integer/float? Assuming that you don't care about IEEE notations like "NaN" or -"Infinity", you probably just want to use a regular expression. +"Infinity", you probably just want to use a regular expression: - if (/\D/) { print "has nondigits\n" } - if (/^\d+$/) { print "is a whole number\n" } - if (/^-?\d+$/) { print "is an integer\n" } - if (/^[+-]?\d+$/) { print "is a +/- integer\n" } - if (/^-?\d+\.?\d*$/) { print "is a real number\n" } - if (/^-?(?:\d+(?:\.\d*)?|\.\d+)$/) { print "is a decimal number\n" } - if (/^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/) - { print "a C float\n" } + use 5.010; + + given( $number ) { + when( /\D/ ) + { say "\thas nondigits"; continue } + when( /^\d+\z/ ) + { say "\tis a whole number"; continue } + when( /^-?\d+\z/ ) + { say "\tis an integer"; continue } + when( /^[+-]?\d+\z/ ) + { say "\tis a +/- integer"; continue } + when( /^-?(?:\d+\.?|\.\d)\d*\z/ ) + { say "\tis a real number"; continue } + when( /^[+-]?(?=\.?\d)\d*\.?\d*(?:e[+-]?\d+)?\z/i) + { say "\tis a C float" } + } There are also some commonly used modules for the task. L<Scalar::Util> (distributed with 5.8) provides access to perl's internal function C<looks_like_number> for determining whether a -variable looks like a number. L<Data::Types> exports functions that +variable looks like a number. L<Data::Types> exports functions that validate data types using both the above and other regular expressions. Thirdly, there is C<Regexp::Common> which has regular expressions to match various types of numbers. Those three modules are available from the CPAN. If you're on a POSIX system, Perl supports the C<POSIX::strtod> -function. Its semantics are somewhat cumbersome, so here's a -C<getnum> wrapper function for more convenient access. This function +function for converting strings to doubles (and also C<POSIX::strtol> +for longs). Its semantics are somewhat cumbersome, so here's a +C<getnum> wrapper function for more convenient access. This function takes a string and returns the number it found, or C<undef> for input -that isn't a C float. The C<is_numeric> function is a front end to +that isn't a C float. The C<is_numeric> function is a front end to C<getnum> if you just want to say, "Is this a float?" sub getnum { @@ -2514,9 +2617,7 @@ C<getnum> if you just want to say, "Is this a float?" sub is_numeric { defined getnum($_[0]) } Or you could check out the L<String::Scanf> module on the CPAN -instead. The C<POSIX> module (part of the standard Perl distribution) -provides the C<strtod> and C<strtol> for converting strings to double -and longs, respectively. +instead. =head2 How do I keep persistent data across program calls? diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq5.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq5.pod index bd969f4393f..76b6d3e0e2e 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq5.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq5.pod @@ -448,12 +448,12 @@ temporary files in one process, use a counter: my $base_name = sprintf "%s/%d-%d-0000", $temp_dir, $$, time; sub temp_file { - local *FH; + my $fh; my $count = 0; - until( defined(fileno(FH)) || $count++ > 100 ) { + until( defined(fileno($fh)) || $count++ > 100 ) { $base_name =~ s/-(\d+)$/"-" . (1 + $1)/e; # O_EXCL is required for security reasons. - sysopen my($fh), $base_name, O_WRONLY|O_EXCL|O_CREAT; + sysopen $fh, $base_name, O_WRONLY|O_EXCL|O_CREAT; } if( defined fileno($fh) ) { @@ -494,8 +494,8 @@ Berkeley-style ps: } We've used a hash slice in order to easily handle the fields of each row. -Storing the keys in an array means it's easy to operate on them as a -group or loop over them with for. It also avoids polluting the program +Storing the keys in an array makes it easy to operate on them as a +group or loop over them with C<for>. It also avoids polluting the program with global variables and using symbolic references. =head2 How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles? @@ -542,7 +542,7 @@ check out the Symbol or IO::Handle modules. =head2 How can I use a filehandle indirectly? X<filehandle, indirect> -An indirect filehandle is using something other than a symbol +An indirect filehandle is the use of something other than a symbol in a place that a filehandle is expected. Here are ways to get indirect filehandles: @@ -553,8 +553,7 @@ to get indirect filehandles: $fh = *SOME_FH{IO}; # blessed IO::Handle from *SOME_FH typeglob Or, you can use the C<new> method from one of the IO::* modules to -create an anonymous filehandle, store that in a scalar variable, -and use it as though it were a normal filehandle. +create an anonymous filehandle and store that in a scalar variable. use IO::Handle; # 5.004 or higher my $fh = IO::Handle->new(); @@ -644,7 +643,54 @@ techniques to make it possible for the intrepid hacker. =head2 How can I write() into a string? X<write, into a string> -See L<perlform/"Accessing Formatting Internals"> for an C<swrite()> function. +(contributed by brian d foy) + +If you want to C<write> into a string, you just have to <open> a +filehandle to a string, which Perl has been able to do since Perl 5.6: + + open FH, '>', \my $string; + write( FH ); + +Since you want to be a good programmer, you probably want to use a lexical +filehandle, even though formats are designed to work with bareword filehandles +since the default format names take the filehandle name. However, you can +control this with some Perl special per-filehandle variables: C<$^>, which +names the top-of-page format, and C<$~> which shows the line format. You have +to change the default filehandle to set these variables: + + open my($fh), '>', \my $string; + + { # set per-filehandle variables + my $old_fh = select( $fh ); + $~ = 'ANIMAL'; + $^ = 'ANIMAL_TOP'; + select( $old_fh ); + } + + format ANIMAL_TOP = + ID Type Name + . + + format ANIMAL = + @## @<<< @<<<<<<<<<<<<<< + $id, $type, $name + . + +Although write can work with lexical or package variables, whatever variables +you use have to scope in the format. That most likely means you'll want to +localize some package variables: + + { + local( $id, $type, $name ) = qw( 12 cat Buster ); + write( $fh ); + } + + print $string; + +There are also some tricks that you can play with C<formline> and the +accumulator variable C<$^A>, but you lose a lot of the value of formats +since C<formline> won't handle paging and so on. You end up reimplementing +formats when you use them. =head2 How can I open a filehandle to a string? X<string> X<open> X<IO::String> X<filehandle> @@ -727,64 +773,64 @@ Within Perl, you may use this directly: =head2 How come when I open a file read-write it wipes it out? X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating> -Because you're using something like this, which truncates the file and +Because you're using something like this, which truncates the file I<then> gives you read-write access: open my $fh, '+>', '/path/name'; # WRONG (almost always) Whoops. You should instead use this, which will fail if the file -doesn't exist. +doesn't exist: open my $fh, '+<', '/path/name'; # open for update Using ">" always clobbers or creates. Using "<" never does either. The "+" doesn't change this. -Here are examples of many kinds of file opens. Those using sysopen() -all assume +Here are examples of many kinds of file opens. Those using C<sysopen> +all assume that you've pulled in the constants from C<Fcntl>: use Fcntl; To open file for reading: - open my $fh, '<', $path or die $!; - sysopen my $fh, $path, O_RDONLY or die $!; + open my $fh, '<', $path or die $!; + sysopen my $fh, $path, O_RDONLY or die $!; To open file for writing, create new file if needed or else truncate old file: - open my $fh, '>', $path or die $!; - sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT or die $!; - sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT, 0666 or die $!; + open my $fh, '>', $path or die $!; + sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT or die $!; + sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT, 0666 or die $!; To open file for writing, create new file, file must not exist: - sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT or die $!; - sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT, 0666 or die $!; + sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT or die $!; + sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT, 0666 or die $!; To open file for appending, create if necessary: - open my $fh, '>>' $path or die $!; - sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT or die $!; - sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT, 0666 or die $!; + open my $fh, '>>' $path or die $!; + sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT or die $!; + sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT, 0666 or die $!; To open file for appending, file must exist: - sysopen my $fh, $path, O_WRONLY|O_APPEND or die $!; + sysopen my $fh, $path, O_WRONLY|O_APPEND or die $!; To open file for update, file must exist: - open my $fh, '+<', $path or die $!; - sysopen my $fh, $path, O_RDWR or die $!; + open my $fh, '+<', $path or die $!; + sysopen my $fh, $path, O_RDWR or die $!; To open file for update, create file if necessary: - sysopen my $fh, $path, O_RDWR|O_CREAT or die $!; - sysopen my $fh, $path, O_RDWR|O_CREAT, 0666 or die $!; + sysopen my $fh, $path, O_RDWR|O_CREAT or die $!; + sysopen my $fh, $path, O_RDWR|O_CREAT, 0666 or die $!; To open file for update, file must not exist: - sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT or die $!; - sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT, 0666 or die $!; + sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT or die $!; + sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT, 0666 or die $!; To open a file without blocking, creating if necessary: @@ -796,7 +842,7 @@ be an atomic operation over NFS. That is, two processes might both successfully create or unlink the same file! Therefore O_EXCL isn't as exclusive as you might wish. -See also the new L<perlopentut>. +See also L<perlopentut>. =head2 Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>? X<argument list too long> @@ -826,13 +872,13 @@ X<filename, special characters> (contributed by Brian McCauley) -The special two argument form of Perl's open() function ignores +The special two-argument form of Perl's open() function ignores trailing blanks in filenames and infers the mode from certain leading characters (or a trailing "|"). In older versions of Perl this was the only version of open() and so it is prevalent in old code and books. -Unless you have a particular reason to use the two argument form you -should use the three argument form of open() which does not treat any +Unless you have a particular reason to use the two-argument form you +should use the three-argument form of open() which does not treat any characters in the filename as special. open my $fh, "<", " file "; # filename is " file " @@ -951,7 +997,7 @@ X<append> X<file, append> If you are on a system that correctly implements C<flock> and you use the example appending code from "perldoc -f flock" everything will be OK even if the OS you are on doesn't implement append mode correctly -(if such a system exists.) So if you are happy to restrict yourself to +(if such a system exists). So if you are happy to restrict yourself to OSs that implement C<flock> (and that's not really much of a restriction) then that is what you should do. @@ -970,7 +1016,7 @@ C<syswrite> function which is simply a wrapper around your system's C<write(2)> system call. There is still a small theoretical chance that a signal will interrupt -the system level C<write()> operation before completion. There is also +the system-level C<write()> operation before completion. There is also a possibility that some STDIO implementations may call multiple system level C<write()>s even if the buffer was empty to start. There may be some systems where this probability is reduced to zero, and this is @@ -1072,26 +1118,6 @@ to each filehandle. =head2 How can I read in an entire file all at once? X<slurp> X<file, slurping> -Are you sure you want to read the entire file and store it in memory? -If you mmap the file, you can virtually load the entire file into a -string without actually storing it in memory: - - use File::Map qw(map_file); - - map_file my $string, $filename; - -Once mapped, you can treat C<$string> as you would any other string. -Since you don't actually load the data, mmap-ing is very fast and does -not increase your memory footprint. - -If you really want to load the entire file, you can use the -C<File::Slurp> module to do it in one step. - - use File::Slurp; - - my $all_of_it = read_file($filename); # entire file in scalar - my @all_lines = read_file($filename); # one line per element - The customary Perl approach for processing all the lines in a file is to do so one line at a time: @@ -1110,14 +1136,37 @@ you see someone do this: my @lines = <INPUT>; You should think long and hard about why you need everything loaded at -once. It's just not a scalable solution. You might also find it more -fun to use the standard Tie::File module, or the DB_File module's -$DB_RECNO bindings, which allow you to tie an array to a file so that -accessing an element the array actually accesses the corresponding +once. It's just not a scalable solution. + +If you "mmap" the file with the File::Map module from +CPAN, you can virtually load the entire file into a +string without actually storing it in memory: + + use File::Map qw(map_file); + + map_file my $string, $filename; + +Once mapped, you can treat C<$string> as you would any other string. +Since you don't necessarily have to load the data, mmap-ing can be +very fast and may not increase your memory footprint. + +You might also find it more +fun to use the standard C<Tie::File> module, or the C<DB_File> module's +C<$DB_RECNO> bindings, which allow you to tie an array to a file so that +accessing an element of the array actually accesses the corresponding line in the file. -You can read the entire filehandle contents into a scalar. +If you want to load the entire file, you can use the C<File::Slurp> +module to do it in one one simple and efficient step: + use File::Slurp; + + my $all_of_it = read_file($filename); # entire file in scalar + my @all_lines = read_file($filename); # one line per element + +Or you can read the entire file contents into a scalar like this: + + my $var; { local $/; open my $fh, '<', $file or die "can't open $file: $!"; @@ -1127,14 +1176,18 @@ You can read the entire filehandle contents into a scalar. That temporarily undefs your record separator, and will automatically close the file at block exit. If the file is already open, just use this: - $var = do { local $/; <$fh> }; + my $var = do { local $/; <$fh> }; + +You can also use a localized C<@ARGV> to eliminate the C<open>: + + my $var = do { local( @ARGV, $/ ) = $file; <> }; -For ordinary files you can also use the read function. +For ordinary files you can also use the C<read> function. read( $fh, $var, -s $fh ); -The third argument tests the byte size of the data on the INPUT filehandle -and reads that many bytes into the buffer $var. +That third argument tests the byte size of the data on the C<$fh> filehandle +and reads that many bytes into the buffer C<$var>. =head2 How can I read in a file by paragraphs? X<file, reading by paragraphs> @@ -1228,7 +1281,7 @@ not POSIX, not Unix, etc.) systems. You should also check out the Frequently Asked Questions list in comp.unix.* for things like this: the answer is essentially the same. -It's very system dependent. Here's one solution that works on BSD +It's very system-dependent. Here's one solution that works on BSD systems: sub key_ready { @@ -1267,7 +1320,7 @@ Or write a small C program using the editor of champions: % ./fionread 0x4004667f -And then hard code it, leaving porting as an exercise to your successor. +And then hard-code it, leaving porting as an exercise to your successor. $FIONREAD = 0x4004667f; # XXX: opsys dependent @@ -1320,7 +1373,7 @@ Or even with a literal numeric descriptor: my $fd = $ENV{MHCONTEXTFD}; open $mhcontext, "<&=$fd"; # like fdopen(3S) -Note that "<&STDIN" makes a copy, but "<&=STDIN" make +Note that "<&STDIN" makes a copy, but "<&=STDIN" makes an alias. That means if you close an aliased handle, all aliases become inaccessible. This is not true with a copied one. diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq6.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq6.pod index 40965d09fcb..3066187fa60 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq6.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq6.pod @@ -5,7 +5,7 @@ perlfaq6 - Regular Expressions =head1 DESCRIPTION This section is surprisingly small because the rest of the FAQ is -littered with answers involving regular expressions. For example, +littered with answers involving regular expressions. For example, decoding a URL and checking whether something is a number are handled with regular expressions, but those answers are found elsewhere in this document (in L<perlfaq9>: "How do I decode or create those %-encodings @@ -34,7 +34,7 @@ comments. The C</x> modifier causes whitespace to be ignored in a regex pattern (except in a character class and a few other places), and also allows you to -use normal comments there, too. As you can imagine, whitespace and comments +use normal comments there, too. As you can imagine, whitespace and comments help a lot. C</x> lets you turn this: @@ -60,9 +60,9 @@ describing the meaning of each part of the pattern. =item Different Delimiters While we normally think of patterns as being delimited with C</> -characters, they can be delimited by almost any character. L<perlre> -describes this. For example, the C<s///> above uses braces as -delimiters. Selecting another delimiter can avoid quoting the +characters, they can be delimited by almost any character. L<perlre> +describes this. For example, the C<s///> above uses braces as +delimiters. Selecting another delimiter can avoid quoting the delimiter within the pattern: s/\/usr\/local/\/usr\/share/g; # bad delimiter choice @@ -70,14 +70,14 @@ delimiter within the pattern: =back -=head2 I'm having trouble matching over more than one line. What's wrong? +=head2 I'm having trouble matching over more than one line. What's wrong? X<regex, multiline> X<regexp, multiline> X<regular expression, multiline> Either you don't have more than one line in the string you're looking at (probably), or else you aren't using the correct modifier(s) on your pattern (possibly). -There are many ways to get multiline data into a string. If you want +There are many ways to get multiline data into a string. If you want it to happen automatically while reading input, you'll want to set $/ (probably to '' for paragraphs or C<undef> for the whole file) to allow you to read more than one line at a time. @@ -85,21 +85,21 @@ allow you to read more than one line at a time. Read L<perlre> to help you decide which of C</s> and C</m> (or both) you might want to use: C</s> allows dot to include newline, and C</m> allows caret and dollar to match next to a newline, not just at the -end of the string. You do need to make sure that you've actually +end of the string. You do need to make sure that you've actually got a multiline string in there. For example, this program detects duplicate words, even when they span -line breaks (but not paragraph ones). For this example, we don't need +line breaks (but not paragraph ones). For this example, we don't need C</s> because we aren't using dot in a regular expression that we want -to cross line boundaries. Neither do we need C</m> because we aren't +to cross line boundaries. Neither do we need C</m> because we aren't wanting caret or dollar to match at any point inside the record next -to newlines. But it's imperative that $/ be set to something other +to newlines. But it's imperative that $/ be set to something other than the default, or else we won't actually ever have a multiline record read in. $/ = ''; # read in whole paragraph, not just one line while ( <> ) { - while ( /\b([\w'-]+)(\s+\1)+\b/gi ) { # word starts alpha + while ( /\b([\w'-]+)(\s+\g1)+\b/gi ) { # word starts alpha print "Duplicate $1 at paragraph $.\n"; } } @@ -194,7 +194,7 @@ Good luck! X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in> X<$RS, regexes in> -$/ has to be a string. You can use these examples if you really need to +$/ has to be a string. You can use these examples if you really need to do this. If you have File::Stream, this is easy. @@ -211,7 +211,7 @@ If you have File::Stream, this is easy. If you don't have File::Stream, you have to do a little more work. You can use the four-argument form of sysread to continually add to -a buffer. After you add to the buffer, you check if you have a +a buffer. After you add to the buffer, you check if you have a complete line (using your regular expression). local $_ = ""; @@ -235,11 +235,11 @@ being in memory at the end. } -=head2 How do I substitute case insensitively on the LHS while preserving case on the RHS? +=head2 How do I substitute case-insensitively on the LHS while preserving case on the RHS? X<replace, case preserving> X<substitute, case preserving> X<substitution, case preserving> X<s, case preserving> -Here's a lovely Perlish solution by Larry Rosler. It exploits +Here's a lovely Perlish solution by Larry Rosler. It exploits properties of bitwise xor on ASCII strings. $_= "this is a TEsT case"; @@ -329,7 +329,7 @@ the case of the last character is used for the rest of the substitution. =head2 How can I make C<\w> match national character sets? X<\w> -Put C<use locale;> in your script. The \w character class is taken +Put C<use locale;> in your script. The \w character class is taken from the current locale. See L<perllocale> for details. @@ -342,7 +342,7 @@ documented in L<perlre>. No matter which locale you are in, the alphabetic characters are the characters in \w without the digits and the underscore. -As a regex, that looks like C</[^\W\d_]/>. Its complement, +As a regex, that looks like C</[^\W\d_]/>. Its complement, the non-alphabetics, is then everything in \W along with the digits and the underscore, or C</[\W\d_]/>. @@ -350,11 +350,11 @@ the digits and the underscore, or C</[\W\d_]/>. X<regex, escaping> X<regexp, escaping> X<regular expression, escaping> The Perl parser will expand $variable and @variable references in -regular expressions unless the delimiter is a single quote. Remember, +regular expressions unless the delimiter is a single quote. Remember, too, that the right-hand side of a C<s///> substitution is considered -a double-quoted string (see L<perlop> for more details). Remember +a double-quoted string (see L<perlop> for more details). Remember also that any regex special characters will be acted on unless you -precede the substitution with \Q. Here's an example: +precede the substitution with \Q. Here's an example: $string = "Placido P. Octopus"; $regex = "P."; @@ -436,16 +436,16 @@ later, you should only see C<re> report that for the first iteration. print STDERR "\t$_ is good!\n" if m/$regex/; } -=head2 How do I use a regular expression to strip C style comments from a file? +=head2 How do I use a regular expression to strip C-style comments from a file? While this actually can be done, it's much harder than you'd think. For example, this one-liner perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c -will work in many but not all cases. You see, it's too simple-minded for +will work in many but not all cases. You see, it's too simple-minded for certain kinds of C programs, in particular, those with what appear to be -comments in quoted strings. For that, you'd need something like this, +comments in quoted strings. For that, you'd need something like this, created by Jeffrey Friedl and later modified by Fred Curtis. $/ = undef; @@ -454,7 +454,7 @@ created by Jeffrey Friedl and later modified by Fred Curtis. print; This could, of course, be more legibly written with the C</x> modifier, adding -whitespace and comments. Here it is expanded, courtesy of Fred Curtis. +whitespace and comments. Here it is expanded, courtesy of Fred Curtis. s{ /\* ## Start of /* ... */ comment @@ -524,7 +524,7 @@ nesting. There are five total groups in angle brackets: <another group <nested once <nested twice> > > and that's it. -The regular expression to match the balanced text uses two new (to +The regular expression to match the balanced text uses two new (to Perl 5.10) regular expression features. These are covered in L<perlre> and this example is a modified version of one in that documentation. @@ -535,11 +535,11 @@ The group C<< [^<>]++ >> finds one or more non-angle brackets without backtracking. Second, the new C<(?PARNO)> refers to the sub-pattern in the -particular capture buffer given by C<PARNO>. In the following regex, -the first capture buffer finds (and remembers) the balanced text, and -you need that same pattern within the first buffer to get past the +particular capture group given by C<PARNO>. In the following regex, +the first capture group finds (and remembers) the balanced text, and +you need that same pattern within the first buffer to get past the nested text. That's the recursive part. The C<(?1)> uses the pattern -in the outer capture buffer as an independent part of the regex. +in the outer capture group as an independent part of the regex. Putting it all together, you have: @@ -552,15 +552,15 @@ Putting it all together, you have: HERE my @groups = $string =~ m/ - ( # start of capture buffer 1 + ( # start of capture group 1 < # match an opening angle bracket (?: [^<>]++ # one or more non angle brackets, non backtracking | - (?1) # found < or >, so recurse to capture buffer 1 + (?1) # found < or >, so recurse to capture group 1 )* > # match a closing angle bracket - ) # end of capture buffer 1 + ) # end of capture group 1 /xg; $" = "\n\t"; @@ -626,13 +626,13 @@ first and the nested matches so up later: Found: <nested twice> -=head2 What does it mean that regexes are greedy? How can I get around it? +=head2 What does it mean that regexes are greedy? How can I get around it? X<greedy> X<greediness> Most people mean that greedy regexes match as much as they can. Technically speaking, it's actually the quantifiers (C<?>, C<*>, C<+>, C<{}>) that are greedy rather than the whole pattern; Perl prefers local -greed and immediate gratification to overall greed. To get non-greedy +greed and immediate gratification to overall greed. To get non-greedy versions of the same quantifiers, use (C<??>, C<*?>, C<+?>, C<{}?>). An example: @@ -642,9 +642,9 @@ An example: $s2 =~ s/ve.*?y //; # I am very cold Notice how the second substitution stopped matching as soon as it -encountered "y ". The C<*?> quantifier effectively tells the regular +encountered "y ". The C<*?> quantifier effectively tells the regular expression engine to find a match as quickly as possible and pass -control on to whatever is next in line, like you would if you were +control on to whatever is next in line, as you would if you were playing hot potato. =head2 How do I process each word on each line? @@ -672,7 +672,7 @@ might consider =head2 How can I print out a word-frequency or line-frequency summary? -To do this, you have to parse out each word in the input stream. We'll +To do this, you have to parse out each word in the input stream. We'll pretend that by word you mean chunk of alphabetics, hyphens, or apostrophes, rather than the non-whitespace chunk idea of a word given in the previous question: @@ -710,40 +710,47 @@ See the module String::Approx available from CPAN. X<regex, efficiency> X<regexp, efficiency> X<regular expression, efficiency> -( contributed by brian d foy ) +(contributed by brian d foy) -Avoid asking Perl to compile a regular expression every time -you want to match it. In this example, perl must recompile -the regular expression for every iteration of the C<foreach> -loop since it has no way to know what $pattern will be. +If you have Perl 5.10 or later, this is almost trivial. You just smart +match against an array of regular expression objects: - @patterns = qw( foo bar baz ); + my @patterns = ( qr/Fr.d/, qr/B.rn.y/, qr/W.lm./ ); + + if( $string ~~ @patterns ) { + ... + }; - LINE: while( <DATA> ) - { - foreach $pattern ( @patterns ) - { - if( /\b$pattern\b/i ) - { +The smart match stops when it finds a match, so it doesn't have to try +every expression. + +Earlier than Perl 5.10, you have a bit of work to do. You want to +avoid compiling a regular expression every time you want to match it. +In this example, perl must recompile the regular expression for every +iteration of the C<foreach> loop since it has no way to know what +C<$pattern> will be: + + my @patterns = qw( foo bar baz ); + + LINE: while( <DATA> ) { + foreach $pattern ( @patterns ) { + if( /\b$pattern\b/i ) { print; next LINE; } } } -The C<qr//> operator showed up in perl 5.005. It compiles a -regular expression, but doesn't apply it. When you use the -pre-compiled version of the regex, perl does less work. In -this example, I inserted a C<map> to turn each pattern into -its pre-compiled form. The rest of the script is the same, -but faster. +The C<qr//> operator showed up in perl 5.005. It compiles a regular +expression, but doesn't apply it. When you use the pre-compiled +version of the regex, perl does less work. In this example, I inserted +a C<map> to turn each pattern into its pre-compiled form. The rest of +the script is the same, but faster: - @patterns = map { qr/\b$_\b/i } qw( foo bar baz ); + my @patterns = map { qr/\b$_\b/i } qw( foo bar baz ); - LINE: while( <> ) - { - foreach $pattern ( @patterns ) - { + LINE: while( <> ) { + foreach $pattern ( @patterns ) { if( /$pattern/ ) { print; @@ -752,22 +759,21 @@ but faster. } } -In some cases, you may be able to make several patterns into -a single regular expression. Beware of situations that require -backtracking though. +In some cases, you may be able to make several patterns into a single +regular expression. Beware of situations that require backtracking +though. - $regex = join '|', qw( foo bar baz ); + my $regex = join '|', qw( foo bar baz ); - LINE: while( <> ) - { + LINE: while( <> ) { print if /\b(?:$regex)\b/i; } For more details on regular expression efficiency, see I<Mastering -Regular Expressions> by Jeffrey Freidl. He explains how regular +Regular Expressions> by Jeffrey Friedl. He explains how regular expressions engine work and why some patterns are surprisingly -inefficient. Once you understand how perl applies regular -expressions, you can tune them for individual situations. +inefficient. Once you understand how perl applies regular expressions, +you can tune them for individual situations. =head2 Why don't word-boundary searches with C<\b> work for me? X<\b> @@ -787,7 +793,7 @@ meaning that it doesn't represent a character in the string, but a condition at a certain position. For the regular expression, /\bPerl\b/, there has to be a word -boundary before the "P" and after the "l". As long as something other +boundary before the "P" and after the "l". As long as something other than a word character precedes the "P" and succeeds the "l", the pattern will match. These strings match /\bPerl\b/. @@ -801,8 +807,8 @@ These strings do not match /\bPerl\b/. "Perl_" # _ is a word char! "Perler" # no word char before P, but one after l -You don't have to use \b to match words though. You can look for -non-word characters surrounded by word characters. These strings +You don't have to use \b to match words though. You can look for +non-word characters surrounded by word characters. These strings match the pattern /\b'\b/. "don't" # the ' char is surrounded by "n" and "t" @@ -843,7 +849,7 @@ really appreciate them. As of the 5.005 release, the $& variable is no longer "expensive" the way the other two are. Since Perl 5.6.1 the special variables @- and @+ can functionally replace -$`, $& and $'. These arrays contain pointers to the beginning and end +$`, $& and $'. These arrays contain pointers to the beginning and end of each match (see perlvar for the full story), so they give you essentially the same information, but without the risk of excessive string copying. @@ -857,12 +863,12 @@ regular expression with the C</p> modifier. X<\G> You use the C<\G> anchor to start the next match on the same -string where the last match left off. The regular +string where the last match left off. The regular expression engine cannot skip over any characters to find the next match with this anchor, so C<\G> is similar to the -beginning of string anchor, C<^>. The C<\G> anchor is typically -used with the C<g> flag. It uses the value of C<pos()> -as the position to start the next match. As the match +beginning of string anchor, C<^>. The C<\G> anchor is typically +used with the C<g> flag. It uses the value of C<pos()> +as the position to start the next match. As the match operator makes successive matches, it updates C<pos()> with the position of the next character past the last match (or the first character of the next match, depending on how you like @@ -870,7 +876,7 @@ to look at it). Each string has its own C<pos()> value. Suppose you want to match all of consecutive pairs of digits in a string like "1122a44" and stop matching when you -encounter non-digits. You want to match C<11> and C<22> but +encounter non-digits. You want to match C<11> and C<22> but the letter <a> shows up between C<22> and C<44> and you want to stop at C<a>. Simply matching pairs of digits skips over the C<a> and still matches C<44>. @@ -879,7 +885,7 @@ the C<a> and still matches C<44>. my @pairs = m/(\d\d)/g; # qw( 11 22 44 ) If you use the C<\G> anchor, you force the match after C<22> to -start with the C<a>. The regular expression cannot match +start with the C<a>. The regular expression cannot match there since it does not find a digit, so the next match fails and the match operator returns the pairs it already found. @@ -939,7 +945,7 @@ which works in 5.004 or later. } For each line, the C<PARSER> loop first tries to match a series -of digits followed by a word boundary. This match has to +of digits followed by a word boundary. This match has to start at the place the last match left off (or the beginning of the string on the first match). Since C<m/ \G( \d+\b )/gcx> uses the C<c> flag, if the string does not match that @@ -947,16 +953,16 @@ regular expression, perl does not reset pos() and the next match starts at the same position to try a different pattern. -=head2 Are Perl regexes DFAs or NFAs? Are they POSIX compliant? +=head2 Are Perl regexes DFAs or NFAs? Are they POSIX compliant? X<DFA> X<NFA> X<POSIX> While it's true that Perl's regular expressions resemble the DFAs (deterministic finite automata) of the egrep(1) program, they are in fact implemented as NFAs (non-deterministic finite automata) to allow -backtracking and backreferencing. And they aren't POSIX-style either, -because those guarantee worst-case behavior for all cases. (It seems +backtracking and backreferencing. And they aren't POSIX-style either, +because those guarantee worst-case behavior for all cases. (It seems that some people prefer guarantees of consistency, even when what's -guaranteed is slowness.) See the book "Mastering Regular Expressions" +guaranteed is slowness.) See the book "Mastering Regular Expressions" (from O'Reilly) by Jeffrey Friedl for all the details you could ever hope to know on these matters (a full citation appears in L<perlfaq2>). @@ -979,14 +985,14 @@ X<regex, and multibyte characters> X<regexp, and multibyte characters> X<regular expression, and multibyte characters> X<martian> X<encoding, Martian> Starting from Perl 5.6 Perl has had some level of multibyte character -support. Perl 5.8 or later is recommended. Supported multibyte +support. Perl 5.8 or later is recommended. Supported multibyte character repertoires include Unicode, and legacy encodings -through the Encode module. See L<perluniintro>, L<perlunicode>, +through the Encode module. See L<perluniintro>, L<perlunicode>, and L<Encode>. If you are stuck with older Perls, you can do Unicode with the C<Unicode::String> module, and character conversions using the -C<Unicode::Map8> and C<Unicode::Map> modules. If you are using +C<Unicode::Map8> and C<Unicode::Map> modules. If you are using Japanese encodings, you might try using the jperl 5.005_03. Finally, the following set of approaches was offered by Jeffrey @@ -1004,9 +1010,9 @@ nine characters 'I', ' ', 'a', 'm', ' ', 'CV', 'SG', 'XX', '!'. Now, say you want to search for the single character C</GX/>. Perl doesn't know about Martian, so it'll find the two bytes "GX" in the "I -am CVSGXX!" string, even though that character isn't there: it just +am CVSGXX!" string, even though that character isn't there: it just looks like it is because "SG" is next to "XX", but there's no real -"GX". This is a big problem. +"GX". This is a big problem. Here are a few ways, all painful, to deal with it: @@ -1040,7 +1046,7 @@ Goldberg, who uses a zero-width negative look-behind assertion. /x; This succeeds if the "martian" character GX is in the string, and fails -otherwise. If you don't like using (?<!), a zero-width negative +otherwise. If you don't like using (?<!), a zero-width negative look-behind assertion, you can replace (?<![A-Z]) with (?:^|[^A-Z]). It does have the drawback of putting the wrong thing in $-[0] and $+[0], @@ -1099,7 +1105,7 @@ for more details). if( $string =~ m/\Q$regex\E/ ) { ... } Alternately, you can use C<qr//>, the regular expression quote operator (see -L<perlop> for more details). It quotes and perhaps compiles the pattern, +L<perlop> for more details). It quotes and perhaps compiles the pattern, and you can apply regular expression flags to the pattern. chomp( my $input = <STDIN> ); @@ -1137,7 +1143,7 @@ This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. Irrespective of its distribution, all code examples in this file -are hereby placed into the public domain. You are permitted and +are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun -or for profit as you see fit. A simple comment in the code giving +or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required. diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq7.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq7.pod index 3782351d68e..fcf270d9ce8 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq7.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq7.pod @@ -29,7 +29,8 @@ They are type specifiers, as detailed in L<perldata>: * for all types of that symbol name. In version 4 you used them like pointers, but in modern perls you can just use references. -There are couple of other symbols that you're likely to encounter that aren't +There are a couple of other symbols that +you're likely to encounter that aren't really type specifiers: <> are used for inputting a record from a filehandle. @@ -48,8 +49,8 @@ I<not> use the brackets. These are correct: C<eof(FH)>, C<seek(FH, 0, Normally, a bareword doesn't need to be quoted, but in most cases probably should be (and must be under C<use strict>). But a hash key -consisting of a simple word (that isn't the name of a defined -subroutine) and the left-hand operand to the C<< => >> operator both +consisting of a simple word and the left-hand +operand to the C<< => >> operator both count as though they were quoted: This is like this @@ -212,23 +213,23 @@ treat each case individually. =over 4 -=item +=item * Get a login for the Perl Authors Upload Server (PAUSE) if you don't already have one: http://pause.perl.org -=item +=item * Write to modules@perl.org explaining what you did to contact the current maintainer. The PAUSE admins will also try to reach the maintainer. -=item +=item * Post a public message in a heavily trafficked site announcing your intention to take over the module. -=item +=item * Wait a bit. The PAUSE admins don't want to act too quickly in case the current maintainer is on holiday. If there's no response to @@ -332,7 +333,7 @@ package: sub next_id { ++$id } } -This is discussed in more detail in L<perlsub>, see the entry on +This is discussed in more detail in L<perlsub>; see the entry on I<Persistent Private Variables>. =head2 What is variable suicide and how can I prevent it? @@ -553,7 +554,7 @@ For instance: Notice how at no point does the value "private" get printed. That's because $var only has that value within the block of the lexical() -function, and it is hidden from called subroutine. +function, and it is hidden from the called subroutine. In summary, local() doesn't make what you think of as private, local variables. It gives a global variable a temporary value. my() is @@ -633,8 +634,7 @@ Why do you want to do that? :-) If you want to override a predefined function, such as open(), then you'll have to import the new definition from a different -module. See L<perlsub/"Overriding Built-in Functions">. There's -also an example in L<perltoot/"Class::Template">. +module. See L<perlsub/"Overriding Built-in Functions">. If you want to overload a Perl operator, such as C<+> or C<**>, then you'll want to use the C<use overload> pragma, documented @@ -797,7 +797,7 @@ out L<perltoot> for details about any of the above cases. You may also use C<print ref($object)> to find out the class C<$object> was blessed into. -Another possible reason for problems is because you've used the +Another possible reason for problems is that you've used the indirect object syntax (eg, C<find Guru "Samy">) on a class name before Perl has seen that such a package exists. It's wisest to make sure your packages are all defined before you start using them, which @@ -831,10 +831,8 @@ diagnostics as C<Carp> does, use the C<caller> built-in: print "I was called from package $package\n"; ); -By default, your program starts in package C<main>, so you should -always be in some package unless someone uses the C<package> built-in -with no namespace. See the C<package> entry in L<perlfunc> for the -details of empty packages. +By default, your program starts in package C<main>, so you will +always be in some package. This is different from finding out the package an object is blessed into, which might not be the current package. For that, use C<blessed> @@ -945,8 +943,8 @@ altogether. Global variables are bad because they can easily collide accidentally and in general make for non-scalable and confusing code. Symbolic references are forbidden under the C<use strict> pragma. -They are not true references and consequently are not reference counted -or garbage collected. +They are not true references and consequently are not reference-counted +or garbage-collected. The other reason why using a variable to hold the name of another variable is a bad idea is that the question often stems from a lack of @@ -983,7 +981,7 @@ make it less confusing, like bracketed percent symbols, etc. $str =~ s/%(\w+)%/$USER_VARS{$1}/g; # no /e here at all Another reason that folks sometimes think they want a variable to -contain the name of a variable is because they don't know how to build +contain the name of a variable is that they don't know how to build proper data structures using hashes. For example, let's say they wanted two hashes in their program: %fred and %barney, and that they wanted to use another scalar variable to refer to those by name. @@ -1004,7 +1002,7 @@ And just use a multilevel hash to start with. The only times that you absolutely I<must> use symbolic references are when you really must refer to the symbol table. This may be because it's -something that can't take a real reference to, such as a format name. +something that one can't take a real reference to, such as a format name. Doing so may also be important for method calls, since these always go through the symbol table for resolution. @@ -1020,8 +1018,8 @@ can play around with the symbol table. For example: All those functions (red(), blue(), green(), etc.) appear to be separate, but the real code in the closure actually was compiled only once. -So, sometimes you might want to use symbolic references to directly -manipulate the symbol table. This doesn't matter for formats, handles, and +So, sometimes you might want to use symbolic references to manipulate +the symbol table directly. This doesn't matter for formats, handles, and subroutines, because they are always global--you can't use my() on them. For scalars, arrays, and hashes, though--and usually for subroutines-- you probably only want to use hard references. diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq8.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq8.pod index 08a5b038b45..b64e8d038b7 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq8.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq8.pod @@ -289,7 +289,7 @@ L<perlfunc/"sysopen"> for more on this approach. Some devices will be expecting a "\r" at the end of each line rather than a "\n". In some ports of perl, "\r" and "\n" are different from -their usual (Unix) ASCII values of "\012" and "\015". You may have to +their usual (Unix) ASCII values of "\015" and "\012". You may have to give the numeric values you want directly, using octal ("\015"), hex ("0x0D"), or as a control-character specification ("\cM"). @@ -524,7 +524,7 @@ L<perlfunc/syscall>. =head2 How can I do an atexit() or setjmp()/longjmp()? (Exception handling) You can use the C<END> block to simulate C<atexit()>. Each package's -C<END> block is called when the program or thread ends See L<perlmod> +C<END> block is called when the program or thread ends. See the L<perlmod> manpage for more details about C<END> blocks. For example, you can use this to make sure your filter program managed @@ -545,7 +545,7 @@ details of this, see the section on signals, especially the time-out handler for a blocking C<flock()> in L<perlipc/"Signals"> or the section on "Signals" in I<Programming Perl>. -If exception handling is all you're interested in, use one of the +If exception handling is all you're interested in, use one of the many CPAN modules that handle exceptions, such as C<Try::Tiny>. If you want the C<atexit()> syntax (and an C<rmexit()> as well), try the @@ -860,7 +860,7 @@ list. Further examples of this can be found in L<perlipc/"Safe Pipe Opens">. Note that if you're using Windows, no solution to this vexing issue is -even possible. Even if Perl were to emulate C<fork()>, you'd still be +even possible. Even though Perl emulates C<fork()>, you'll still be stuck, because Windows does not have an argc/argv-style API. =head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)? @@ -933,7 +933,7 @@ approach will suffice: =head2 How can I write expect in Perl? -Once upon a time, there was a library called L<chat2.pl> (part of the +Once upon a time, there was a library called F<chat2.pl> (part of the standard perl distribution), which never really got finished. If you find it somewhere, I<don't use it>. These days, your best bet is to look at the Expect module available from CPAN, which also requires two @@ -1192,7 +1192,7 @@ might not be perl's message. (contributed by brian d foy) The easiest way is to have a module also named CPAN do it for you by using -the C<cpan> command the comes with Perl. You can give it a list of modules +the C<cpan> command that comes with Perl. You can give it a list of modules to install: $ cpan IO::Interactive Getopt::Whatever @@ -1263,7 +1263,7 @@ See the entry for C<use> in L<perlfunc> for more details. =head2 How do I keep my own module/library directory? -When you build modules, tell Perl where to install the modules. +When you build modules, tell Perl where to install the modules. If you want to install modules for your own use, the easiest way might be C<local::lib>, which you can download from CPAN. It sets various @@ -1302,11 +1302,11 @@ include path (@INC) at runtime?> for details on how to run your newly installed modules. There is one caveat with INSTALL_BASE, though, since it acts -differently than the PREFIX and LIB settings that older versions of +differently from the PREFIX and LIB settings that older versions of C<ExtUtils::MakeMaker> advocated. INSTALL_BASE does not support installing modules for multiple versions of Perl or different -architectures under the same directory. You should consider if you -really want that , and if you do, use the older PREFIX and LIB +architectures under the same directory. You should consider whether you +really want that and, if you do, use the older PREFIX and LIB settings. See the C<ExtUtils::Makemaker> documentation for more details. =head2 How do I add the directory my program lives in to the module/library search path? @@ -1349,9 +1349,9 @@ directory of the currently running script and puts it in C<$Bin>, which you can then use to construct the right library path: use FindBin qw($Bin); - + You can also use C<local::lib> to do much of the same thing. Install -modules using C<local::lib>'s settings then use the module in your +modules using C<local::lib>'s settings then use the module in your program: use local::lib; # sets up a local lib at ~/perl5 @@ -1386,13 +1386,13 @@ environment variables, run-time switches, and in-code statements: =item the C<local::lib> module: use local::lib; - + use local::lib "~/myown_perllib"; - + =back -The last is particularly useful because it knows about machine -dependent architectures. The C<lib.pm> pragmatic module was first +The last is particularly useful because it knows about machine-dependent +architectures. The C<lib.pm> pragmatic module was first included with the 5.002 release of Perl. =head2 What is socket.ph and where do I get it? diff --git a/Master/tlpkg/tlperl/lib/pods/perlfaq9.pod b/Master/tlpkg/tlperl/lib/pods/perlfaq9.pod index fa9ef116737..d00d918deb2 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfaq9.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfaq9.pod @@ -19,8 +19,6 @@ comp.infosystems.www.authoring.cgi The CGI specification is outlined in an informational RFC: http://www.ietf.org/rfc/rfc3875 -Other relevant documentation listed in: http://www.perl.org/CGI_MetaFAQ.html - These Perl FAQs very selectively cover some CGI issues. However, Perl programmers are strongly advised to use the C<CGI.pm> module, to take care of the details for them. @@ -38,37 +36,27 @@ job to create an accurate HTTP response based on it). So "\n" written in text mode is technically correct, and recommended. NPH scripts are more tricky: they must put out a complete and accurate set of HTTP transaction response headers; the HTTP specification calls for records -to be terminated with carriage-return and line-feed, i.e ASCII \015\012 +to be terminated with carriage-return and line-feed; i.e., ASCII \015\012 written in binary mode. Using C<CGI.pm> gives excellent platform independence, including EBCDIC systems. C<CGI.pm> selects an appropriate newline representation (C<$CGI::CRLF>) and sets binmode as appropriate. -=head2 My CGI script runs from the command line but not the browser. (500 Server Error) - -Several things could be wrong. You can go through the "Troubleshooting -Perl CGI scripts" guide at +=head2 My CGI script runs from the command line but not the browser. (500 Server Error) - http://www.perl.org/troubleshooting_CGI.html - -If, after that, you can demonstrate that you've read the FAQs and that -your problem isn't something simple that can be easily answered, you'll -probably receive a courteous and useful reply to your question if you -post it on comp.infosystems.www.authoring.cgi (if it's something to do -with HTTP or the CGI protocols). Questions that appear to be Perl -questions but are really CGI ones that are posted to comp.lang.perl.misc -are not so well received. +(contributed by brian d foy) -The useful FAQs, related documents, and troubleshooting guides are -listed in the CGI Meta FAQ: +There are many things that might be wrong with your CGI program, and only +some of them might be related to Perl. Try going through the troubleshooting +guide on Perlmonks: - http://www.perl.org/CGI_MetaFAQ.html + http://www.perlmonks.org/?node_id=380424 =head2 How can I get better error messages from a CGI program? Use the C<CGI::Carp> module. It replaces C<warn> and C<die>, plus the -normal C<Carp> modules C<carp>, C<croak>, and C<confess> functions with +normal C<Carp> module's C<carp>, C<croak>, and C<confess> functions with more verbose and safer versions. It still sends them to the normal server error log. @@ -108,13 +96,13 @@ attempts to do a little simple formatting of the resulting plain text. Many folks attempt a simple-minded regular expression approach, like C<< s/<.*?>//g >>, but that fails in many cases because the tags may continue over line breaks, they may contain quoted angle-brackets, -or HTML comment may be present. Plus, folks forget to convert +or HTML comments may be present. Plus, folks forget to convert entities--like C<<> for example. Here's one "simple-minded" approach, that works for most files: #!/usr/bin/perl -p0777 - s/<(?:[^>'"]*|(['"]).*?\1)*>//gs + s/<(?:[^>'"]*|(['"]).*?\g1)*>//gs If you want a more complete solution, see the 3-stage striphtml program in @@ -159,14 +147,14 @@ You can use C<URI::Find> to extract URLs from an arbitrary text document. Less complete solutions involving regular expressions can save you a lot of processing time if you know that the input is simple. One solution from Tom Christiansen runs 100 times faster than most -module based approaches but only extracts URLs from anchors where the first +module-based approaches but only extracts URLs from anchors where the first attribute is HREF and there are no other attributes. #!/usr/bin/perl -n00 # qxurl - tchrist@perl.com print "$2\n" while m{ < \s* - A \s+ HREF \s* = \s* (["']) (.*?) \1 + A \s+ HREF \s* = \s* (["']) (.*?) \g1 \s* > }gsix; @@ -273,7 +261,7 @@ either on the way in or the way out. If you have to encode a string yourself, remember that you should never try to encode an already-composed URI. You need to escape the components separately then put them together. To encode a string, you -can use the the C<URI::Escape> module. The C<uri_escape> function +can use the C<URI::Escape> module. The C<uri_escape> function returns the escaped string: my $original = "Colon : Hash # Percent %"; @@ -351,9 +339,21 @@ a DBI compatible driver. C<HTTPD::UserAdmin> supports files used by the =head2 How do I make sure users can't enter values into a form that cause my CGI script to do bad things? -See the security references listed in the CGI Meta FAQ +(contributed by brian d foy) + +You can't prevent people from sending your script bad data. Even if +you add some client-side checks, people may disable them or bypass +them completely. For instance, someone might use a module such as +C<LWP> to access your CGI program. If you want to prevent data that +try to use SQL injection or other sorts of attacks (and you should +want to), you have to not trust any data that enter your program. - http://www.perl.org/CGI_MetaFAQ.html +The L<perlsec> documentation has general advice about data security. +If you are using the C<DBI> module, use placeholder to fill in data. +If you are running external programs with C<system> or C<exec>, use +the list forms. There are many other precautions that you should take, +too many to list here, and most of them fall under the category of not +using any data that you don't intend to use. Trust no one. =head2 How do I parse a mail header? @@ -657,12 +657,23 @@ This can make tasks like fetching the newsgroup list as simple as =head2 How do I fetch/put an FTP file? -C<LWP::Simple> (available from CPAN) can fetch but not put. C<Net::FTP> (also -available from CPAN) is more complex but can put as well as fetch. +(contributed by brian d foy) + +The C<LWP> family of modules (available on CPAN as the libwww-perl distribution) +can work with FTP just like it can with many other protocols. C<LWP::Simple> +makes it quite easy to fetch a file: + + use LWP::Simple; + + my $data = get( 'ftp://some.ftp.site/some/file.txt' ); + +If you want more direct or low-level control of the FTP process, you can use +the C<Net::FTP> module (in the Standard Library since Perl 5.8). It's +documentation has examples showing you just how to do that. =head2 How can I do RPC in Perl? -(Contributed by brian d foy) +(contributed by brian d foy) Use one of the RPC modules you can find on CPAN ( http://search.cpan.org/search?query=RPC&mode=all ). diff --git a/Master/tlpkg/tlperl/lib/pods/perlfilter.pod b/Master/tlpkg/tlperl/lib/pods/perlfilter.pod index ca5cfd9fb2e..27061883c1f 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfilter.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfilter.pod @@ -217,7 +217,7 @@ difficult for the potential cracker. The most important: Write your decryption filter in C and statically link the decryption module into the Perl binary. For further tips to make life difficult for the potential cracker, see the file I<decrypt.pm> in the source filters -module. +distribution. =back @@ -234,7 +234,7 @@ The source filter distribution includes two modules that simplify this task: C<Filter::exec> and C<Filter::sh>. Both allow you to run any external executable. Both use a coprocess to control the flow of data into and out of the external executable. (For details on coprocesses, -see Stephens, W.R. "Advanced Programming in the UNIX Environment." +see Stephens, W.R., "Advanced Programming in the UNIX Environment." Addison-Wesley, ISBN 0-210-56317-7, pages 441-445.) The difference between them is that C<Filter::exec> spawns the external command directly, while C<Filter::sh> spawns a shell to execute the external @@ -388,9 +388,9 @@ Two special marker lines will bracket debugging code, like this: } ## DEBUG_END -When the C<DEBUG> environment variable exists, the filter ensures that -Perl parses only the code between the C<DEBUG_BEGIN> and C<DEBUG_END> -markers. That means that when C<DEBUG> does exist, the code above +The filter ensures that Perl parses the code between the <DEBUG_BEGIN> +and C<DEBUG_END> markers only when the C<DEBUG> environment variable +exists. That means that when C<DEBUG> does exist, the code above should be passed through the filter unchanged. The marker lines can also be passed through as-is, because the Perl parser will see them as comment lines. When C<DEBUG> isn't set, we need a way to disable the diff --git a/Master/tlpkg/tlperl/lib/pods/perlfork.pod b/Master/tlpkg/tlperl/lib/pods/perlfork.pod index 48d65ed4c58..709d053d28e 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfork.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfork.pod @@ -37,7 +37,7 @@ thread that implements this child "process" as the pseudo-process. To the Perl program that called fork(), all this is designed to be transparent. The parent returns from the fork() with a pseudo-process -ID that can be subsequently used in any process manipulation functions; +ID that can be subsequently used in any process-manipulation functions; the child returns from the fork() with a value of C<0> to signify that it is the child pseudo-process. @@ -77,12 +77,24 @@ and return its status. =item kill() -kill() can be used to terminate a pseudo-process by passing it the ID returned -by fork(). This should not be used except under dire circumstances, because -the operating system may not guarantee integrity of the process resources -when a running thread is terminated. Note that using kill() on a -pseudo-process() may typically cause memory leaks, because the thread that -implements the pseudo-process does not get a chance to clean up its resources. +C<kill('KILL', ...)> can be used to terminate a pseudo-process by +passing it the ID returned by fork(). This should not be used except +under dire circumstances, because the operating system may not +guarantee integrity of the process resources when a running thread is +terminated. Note that using C<kill('KILL', ...)> on a +pseudo-process() may typically cause memory leaks, because the thread +that implements the pseudo-process does not get a chance to clean up +its resources. + +C<kill('TERM', ...)> can also be used on pseudo-processes, but the +signal will not be delivered while the pseudo-process is blocked by a +system call, e.g. waiting for a socket to connect, or trying to read +from a socket with no data available. Starting in Perl 5.14 the +parent process will not wait for children to exit once they have been +signalled with C<kill('TERM', ...)> to avoid deadlock during process +exit. You will have to explicitly call waitpid() to make sure the +child has time to clean-up itself, but you are then also responsible +that the child is not blocking on I/O either. =item exec() @@ -137,11 +149,12 @@ to complete before they exit. This means that the parent and every pseudo-child created by it that is also a pseudo-parent will only exit after their pseudo-children have exited. -A way to mark a pseudo-processes as running detached from their parent (so -that the parent would not have to wait() for them if it doesn't want to) -will be provided in future. +Starting with Perl 5.14 a parent will not wait() automatically +for any child that has been signalled with C<sig('TERM', ...)> +to avoid a deadlock in case the child is blocking on I/O and +never receives the signal. -=head2 CAVEATS AND LIMITATIONS +=head1 CAVEATS AND LIMITATIONS =over 8 @@ -184,9 +197,22 @@ On some operating systems, notably Solaris and Unixware, calling C<exit()> from a child process will flush and close open filehandles in the parent, thereby corrupting the filehandles. On these systems, calling C<_exit()> is suggested instead. C<_exit()> is available in Perl through the -C<POSIX> module. Please consult your systems manpages for more information +C<POSIX> module. Please consult your system's manpages for more information on this. +=item Open directory handles + +Perl will completely read from all open directory handles until they +reach the end of the stream. It will then seekdir() back to the +original location and all future readdir() requests will be fulfilled +from the cache buffer. That means that neither the directory handle held +by the parent process nor the one held by the child process will see +any changes made to the directory after the fork() call. + +Note that rewinddir() has a similar limitation on Windows and will not +force readdir() to read the directory again either. Only a newly +opened directory handle will reflect changes to the directory. + =item Forking pipe open() not yet implemented The C<open(FOO, "|-")> and C<open(BAR, "-|")> constructs are not yet diff --git a/Master/tlpkg/tlperl/lib/pods/perlform.pod b/Master/tlpkg/tlperl/lib/pods/perlform.pod index 3cfa1b768d0..a2aa6588b76 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlform.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlform.pod @@ -65,7 +65,7 @@ X<@*> X<^*> X<~> X<~~> < pad character for left justification | pad character for centering > pad character for right justification - # pad character for a right justified numeric field + # pad character for a right-justified numeric field 0 instead of first #: pad number with leading zeroes . decimal point within a numeric field ... terminate a text field, show "..." as truncation evidence @@ -122,7 +122,7 @@ filled with "#" as overflow evidence. 42 3.142 0.000 0 #### -=head2 The Field @* for Variable Width Multi-Line Text +=head2 The Field @* for Variable-Width Multi-Line Text X<@*> The field "@*" can be used for printing multi-line, nontruncated @@ -130,10 +130,10 @@ values; it should (but need not) appear by itself on a line. A final line feed is chomped off, but all other characters are emitted verbatim. -=head2 The Field ^* for Variable Width One-line-at-a-time Text +=head2 The Field ^* for Variable-Width One-line-at-a-time Text X<^*> -Like "@*", this is a variable width field. The value supplied must be a +Like "@*", this is a variable-width field. The value supplied must be a scalar variable. Perl puts the first line (up to the first "\n") of the text into the field, and then chops off the front of the string so that the next time the variable is referenced, more of the text can be printed. @@ -166,9 +166,9 @@ token on the first line. If an expression evaluates to a number with a decimal part, and if the corresponding picture specifies that the decimal part should appear in the output (that is, any picture except multiple "#" characters B<without> an embedded "."), the character used for the decimal -point is B<always> determined by the current LC_NUMERIC locale. This -means that, if, for example, the run-time environment happens to specify a -German locale, "," will be used instead of the default ".". See +point is determined by the current LC_NUMERIC locale if C<use locale> is in +effect. This means that, if, for example, the run-time environment happens +to specify a German locale, "," will be used instead of the default ".". See L<perllocale> and L<"WARNINGS"> for more information. @@ -182,7 +182,7 @@ the field, and then chops off the front of the string so that the next time the variable is referenced, more of the text can be printed. (Yes, this means that the variable itself is altered during execution of the write() call, and is not restored.) The next portion of text is determined by -a crude line breaking algorithm. You may use the carriage return character +a crude line-breaking algorithm. You may use the carriage return character (C<\r>) to force a line break. You can change which characters are legal to break on by changing the variable C<$:> (that's $FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a @@ -291,7 +291,7 @@ one to affect them: Pretty ugly, eh? It's a common idiom though, so don't be too surprised when you see it. You can at least use a temporary variable to hold the previous filehandle: (this is a much better approach in general, -because not only does legibility improve, you now have intermediary +because not only does legibility improve, you now have an intermediary stage in the expression to single-step the debugger through): $ofh = select(OUTF); @@ -393,7 +393,7 @@ by checking $FORMAT_LINES_LEFT before each write() and print the footer yourself if necessary. Here's another strategy: Open a pipe to yourself, using C<open(MYSELF, "|-")> -(see L<perlfunc/open()>) and always write() to MYSELF instead of STDOUT. +(see L<perlfunc/"open FILEHANDLE">) and always write() to MYSELF instead of STDOUT. Have your child process massage its STDIN to rearrange headers and footers however you like. Not very convenient, but doable. @@ -442,17 +442,13 @@ Lexical variables (declared with "my") are not visible within a format unless the format is declared within the scope of the lexical variable. (They weren't visible at all before version 5.001.) -Formats are the only part of Perl that unconditionally use information -from a program's locale; if a program's environment specifies an -LC_NUMERIC locale, it is always used to specify the decimal point -character in formatted output. Perl ignores all other aspects of locale -handling unless the C<use locale> pragma is in effect. Formatted output -cannot be controlled by C<use locale> because the pragma is tied to the -block structure of the program, and, for historical reasons, formats -exist outside that block structure. See L<perllocale> for further -discussion of locale handling. - -Within strings that are to be displayed in a fixed length text field, +If a program's environment specifies an LC_NUMERIC locale and C<use +locale> is in effect when the format is declared, the locale is used +to specify the decimal point character in formatted output. Formatted +output cannot be controlled by C<use locale> at the time when write() +is called. See L<perllocale> for further discussion of locale handling. + +Within strings that are to be displayed in a fixed-length text field, each control character is substituted by a space. (But remember the special meaning of C<\r> when using fill mode.) This is done to avoid misalignment when control characters "disappear" on some output media. diff --git a/Master/tlpkg/tlperl/lib/pods/perlfreebsd.pod b/Master/tlpkg/tlperl/lib/pods/perlfreebsd.pod index 77c297bec6d..00a40593a36 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfreebsd.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfreebsd.pod @@ -24,20 +24,12 @@ which has been integrated into FreeBSD 4.6. perl 5.8.0 sets C<$^X> where possible to a full path by asking the operating system. On FreeBSD the full path of the perl interpreter is found by reading -the symlink F</proc/curproc/file>. There is a bug on FreeBSD, where the -result of reading this symlink is can be wrong in certain circumstances +the symlink F</proc/curproc/file>. FreeBSD has a bug where reading this +symlink sometimes returns an incorrect value (see http://www.freebsd.org/cgi/query-pr.cgi?pr=35703 ). In these cases perl will fall back to the old behaviour of using C's argv[0] value for C<$^X>. -=head2 Perl will no longer be part of "base FreeBSD" - -Not as bad as it sounds--what this means is that Perl will no longer be -part of the B<kernel build system> of FreeBSD. Perl will still very -probably be part of the "default install", and in any case the latest -version will be in the ports system. The first FreeBSD version this -change will affect is 5.0, all 4.n versions will keep the status quo. - =head1 AUTHOR Nicholas Clark <nick@ccl4.org>, collating wisdom supplied by Slaven Rezic diff --git a/Master/tlpkg/tlperl/lib/pods/perlfunc.pod b/Master/tlpkg/tlperl/lib/pods/perlfunc.pod index 6b454cc9a59..2ee3637c121 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlfunc.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlfunc.pod @@ -12,7 +12,7 @@ following comma. (See the precedence table in L<perlop>.) List operators take more than one argument, while unary operators can never take more than one argument. Thus, a comma terminates the argument of a unary operator, but merely separates the arguments of a list -operator. A unary operator generally provides a scalar context to its +operator. A unary operator generally provides scalar context to its argument, while a list operator may provide either scalar or list contexts for its arguments. If it does both, scalar arguments come first and list argument follow, and there can only ever @@ -55,8 +55,8 @@ and C<endpwent>. For example, C<time+86_400> always means C<time() + 86_400>. For functions that can be used in either a scalar or list context, -nonabortive failure is generally indicated in a scalar context by -returning the undefined value, and in a list context by returning the +nonabortive failure is generally indicated in scalar context by +returning the undefined value, and in list context by returning the empty list. Remember the following important rule: There is B<no rule> that relates @@ -79,10 +79,10 @@ there, not the list construction version of the comma. That means it was never a list to start with. In general, functions in Perl that serve as wrappers for system calls ("syscalls") -of the same name (like chown(2), fork(2), closedir(2), etc.) all return +of the same name (like chown(2), fork(2), closedir(2), etc.) return true when they succeed and C<undef> otherwise, as is usually mentioned in the descriptions below. This is different from the C interfaces, -which return C<-1> on failure. Exceptions to this rule are C<wait>, +which return C<-1> on failure. Exceptions to this rule include C<wait>, C<waitpid>, and C<syscall>. System calls also set the special C<$!> variable on failure. Other functions do not, except accidentally. @@ -125,7 +125,7 @@ C<sin>, C<sqrt>, C<srand> =item Functions for real @ARRAYs X<array> -C<pop>, C<push>, C<shift>, C<splice>, C<unshift> +C<each>, C<keys>, C<pop>, C<push>, C<shift>, C<splice>, C<unshift>, C<values> =item Functions for list data X<list> @@ -146,7 +146,7 @@ C<readdir>, C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>, C<syscall>, C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>, C<warn>, C<write> -=item Functions for fixed length data or records +=item Functions for fixed-length data or records C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec> @@ -164,20 +164,20 @@ X<control flow> C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>, C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray> -=item Keywords related to switch +=item Keywords related to the switch feature -C<break>, C<continue>, C<given>, C<when>, C<default> +C<break>, C<continue>, C<default, >C<given>, C<when> -(These are available only if you enable the C<"switch"> feature. -See L<feature> and L<perlsyn/"Switch statements">.) +These are available only if you enable the C<"switch"> feature. +See L<feature> and L<perlsyn/"Switch statements">. +Alternately, include a C<use v5.10> or later to the current scope. =item Keywords related to scoping -C<caller>, C<import>, C<local>, C<my>, C<our>, C<state>, C<package>, -C<use> +C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<state>, C<use> -(C<state> is available only if the C<"state"> feature is enabled. See -L<feature>.) +C<state> is available only if the C<"state"> feature is enabled. See +L<feature>. Alternately, include a C<use v5.10> or later to the current scope. =item Miscellaneous functions @@ -259,7 +259,7 @@ X<portability> X<Unix> X<portable> Perl was born in Unix and can therefore access all common Unix system calls. In non-Unix environments, the functionality of some -Unix system calls may not be available, or details of the available +Unix system calls may not be available or details of the available functionality may differ slightly. The Perl functions affected by this are: @@ -349,6 +349,20 @@ Example: #... } +Note that C<-s/a/b/> does not do a negated substitution. Saying +C<-exp($foo)> still works as expected, however: only single letters +following a minus are interpreted as file tests. + +These operators are exempt from the "looks like a function rule" described +above. That is, an opening parenthesis after the operator does not affect +how much of the following code constitutes the argument. Put the opening +parentheses before the operator to separate it from code that follows (this +applies only to operators with higher precedence than unary operators, of +course): + + -s($file) + 1024 # probably wrong; same as -s($file + 1024) + (-s $file) + 1024 # correct + The interpretation of the file permission operators C<-r>, C<-R>, C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode of the file and the uids and gids of the user. There may be other @@ -367,8 +381,8 @@ or temporarily set their effective uid to something else. If you are using ACLs, there is a pragma called C<filetest> that may produce more accurate results than the bare stat() mode bits. -When under the C<use filetest 'access'> the above-mentioned filetests -test whether the permission can (not) be granted using the +When under C<use filetest 'access'> the above-mentioned filetests +test whether the permission can(not) be granted using the access(2) family of system calls. Also note that the C<-x> and C<-X> may under this pragma return true even if there are no execute permission bits set (nor any extra execute permission ACLs). This strangeness is @@ -378,10 +392,6 @@ filehandle won't cache the results of the file tests when this pragma is in effect. Read the documentation for the C<filetest> pragma for more information. -Note that C<-s/a/b/> does not do a negated substitution. Saying -C<-exp($foo)> still works as expected, however: only single letters -following a minus are interpreted as file tests. - The C<-T> and C<-B> switches work as follows. The first block or so of the file is examined for odd characters such as strange control codes or characters with the high bit set. If too many strange characters (>30%) @@ -393,7 +403,7 @@ file, or a file at EOF when testing a filehandle. Because you have to read a file to do the C<-T> test, on most occasions you want to use a C<-f> against the file first, as in C<next unless -f $file && -T $file>. -If any of the file tests (or either the C<stat> or C<lstat> operators) are given +If any of the file tests (or either the C<stat> or C<lstat> operator) is given the special filehandle consisting of a solitary underline, then the stat structure of the previous file test (or stat operator) is used, saving a system call. (This doesn't work with C<-t>, and you need to remember @@ -522,18 +532,18 @@ binary and text files. If FILEHANDLE is an expression, the value is taken as the name of the filehandle. Returns true on success, otherwise it returns C<undef> and sets C<$!> (errno). -On some systems (in general, DOS and Windows-based systems) binmode() +On some systems (in general, DOS- and Windows-based systems) binmode() is necessary when you're not working with a text file. For the sake -of portability it is a good idea to always use it when appropriate, -and to never use it when it isn't appropriate. Also, people can -set their I/O to be by default UTF-8 encoded Unicode, not bytes. +of portability it is a good idea always to use it when appropriate, +and never to use it when it isn't appropriate. Also, people can +set their I/O to be by default UTF8-encoded Unicode, not bytes. In other words: regardless of platform, use binmode() on binary data, -like for example images. +like images, for example. If LAYER is present it is a single string, but may contain multiple directives. The directives alter the behaviour of the filehandle. -When LAYER is present using binmode on a 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 @@ -555,44 +565,45 @@ functionality has moved from "discipline" to "layer". All documentation of this version of Perl therefore refers to "layers" rather than to "disciplines". Now back to the regularly scheduled documentation...> -To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(utf8)>. +To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(UTF-8)>. C<:utf8> just marks the data as UTF-8 without further checking, -while C<:encoding(utf8)> checks the data for actually being valid +while C<:encoding(UTF-8)> checks the data for actually being valid UTF-8. More details can be found in L<PerlIO::encoding>. In general, binmode() should be called after open() but before any I/O is done on the filehandle. Calling binmode() normally flushes any pending buffered output data (and perhaps pending input data) on the handle. An exception to this is the C<:encoding> layer that -changes the default character encoding of the handle, see L<open>. +changes the default character encoding of the handle; see L</open>. The C<:encoding> layer sometimes needs to be called in mid-stream, and it doesn't flush the stream. The C<:encoding> also implicitly pushes on top of itself the C<:utf8> layer because internally Perl operates on UTF8-encoded Unicode characters. The operating system, device drivers, C libraries, and Perl run-time -system all work together to let the programmer treat a single -character (C<\n>) as the line terminator, irrespective of the external +system all conspire to let the programmer treat a single +character (C<\n>) as the line terminator, irrespective of external representation. On many operating systems, the native text file representation matches the internal representation, but on some platforms the external representation of C<\n> is made up of more than one character. -Mac OS, all variants of Unix, and Stream_LF files on VMS use a single -character to end each line in the external representation of text (even -though that single character is CARRIAGE RETURN on Mac OS and LINE FEED -on Unix and most VMS files). In other systems like OS/2, DOS and the -various flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, -but what's stored in text files are the two characters C<\cM\cJ>. That -means that, if you don't use binmode() on these systems, C<\cM\cJ> -sequences on disk will be converted to C<\n> on input, and any C<\n> in -your program will be converted back to C<\cM\cJ> on output. This is what -you want for text files, but it can be disastrous for binary files. +All variants of Unix, Mac OS (old and new), and Stream_LF files on VMS use +a single character to end each line in the external representation of text +(even though that single character is CARRIAGE RETURN on old, pre-Darwin +flavors of Mac OS, and is LINE FEED on Unix and most VMS files). In other +systems like OS/2, DOS, and the various flavors of MS-Windows, your program +sees a C<\n> as a simple C<\cJ>, but what's stored in text files are the +two characters C<\cM\cJ>. That means that if you don't use binmode() on +these systems, C<\cM\cJ> sequences on disk will be converted to C<\n> on +input, and any C<\n> in your program will be converted back to C<\cM\cJ> on +output. This is what you want for text files, but it can be disastrous for +binary files. Another consequence of using binmode() (on some systems) is that special end-of-file markers will be seen as part of the data stream. -For systems from the Microsoft family this means that if your binary -data contains C<\cZ>, the I/O subsystem will regard it as the end of +For systems from the Microsoft family this means that, if your binary +data contain C<\cZ>, the I/O subsystem will regard it as the end of the file, unless you use binmode(). binmode() is important not only for readline() and print() operations, @@ -626,8 +637,9 @@ See L<perlmod/"Perl Modules">. Break out of a C<given()> block. -This keyword is enabled by the C<"switch"> feature: see L<feature> -for more information. +This keyword is enabled by the C<"switch"> feature: see +L<feature> for more information. Alternately, include a C<use +v5.10> or later to the current scope. =item caller EXPR X<caller> X<call stack> X<stack> X<stack trace> @@ -681,7 +693,7 @@ might not return information about the call frame you expect it to, for C<< N > 1 >>. In particular, C<@DB::args> might have information from the previous time C<caller> was called. -Also be aware that setting C<@DB::args> is I<best effort>, intended for +Be aware that setting C<@DB::args> is I<best effort>, intended for debugging or generating backtraces, and should not be relied upon. In particular, as C<@_> contains aliases to the caller's arguments, Perl does not take a copy of C<@_>, so C<@DB::args> will contain modifications the @@ -689,9 +701,9 @@ subroutine makes to C<@_> or its contents, not the original values at call time. C<@DB::args>, like C<@_>, does not hold explicit references to its elements, so under certain cases its elements may have become freed and reallocated for other variables or temporary values. Finally, a side effect -of the current implementation means that the effects of C<shift @_> can -I<normally> be undone (but not C<pop @_> or other splicing, and not if a -reference to C<@_> has been taken, and subject to the caveat about reallocated +of the current implementation is that the effects of C<shift @_> can +I<normally> be undone (but not C<pop @_> or other splicing, I<and> not if a +reference to C<@_> has been taken, I<and> subject to the caveat about reallocated elements), so C<@DB::args> is actually a hybrid of the current state and initial state of C<@_>. Buyer beware. @@ -714,17 +726,17 @@ neither is set, C<chdir> does nothing. It returns true on success, false otherwise. See the example under C<die>. On systems that support fchdir(2), you may pass a filehandle or -directory handle as argument. On systems that don't support fchdir(2), +directory handle as the argument. On systems that don't support fchdir(2), passing handles raises an exception. =item chmod LIST X<chmod> X<permission> X<mode> Changes the permissions of a list of files. The first element of the -list must be the numerical mode, which should probably be an octal +list must be the numeric mode, which should probably be an octal number, and which definitely should I<not> be a string of octal digits: C<0644> is okay, but C<"0644"> is not. Returns the number of files -successfully changed. See also L</oct>, if all you have is a string. +successfully changed. See also L</oct> if all you have is a string. $cnt = chmod 0755, "foo", "bar"; chmod 0755, @executables; @@ -764,7 +776,7 @@ remove the newline from the end of an input record when you're worried that the final record may be missing its newline. When in paragraph mode (C<$/ = "">), it removes all trailing newlines from the string. When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is -a reference to an integer or the like, see L<perlvar>) chomp() won't +a reference to an integer or the like; see L<perlvar>) chomp() won't remove anything. If VARIABLE is omitted, it chomps C<$_>. Example: @@ -893,7 +905,7 @@ X<close> Closes the file or pipe associated with the filehandle, flushes the IO buffers, and closes the system file descriptor. Returns true if those -operations have succeeded and if no error was reported by any PerlIO +operations succeed and if no error was reported by any PerlIO layer. Closes the currently selected filehandle if the argument is omitted. @@ -910,6 +922,10 @@ on the pipe to exit--in case you wish to look at the output of the pipe afterwards--and implicitly puts the exit status value of that command into C<$?> and C<${^CHILD_ERROR_NATIVE}>. +If there are multiple threads running, C<close> on a filehandle from a +piped open returns true without waiting for the child process to terminate, +if the filehandle is still open in another thread. + Closing the read end of a pipe before the process writing to it at the other end is done writing results in the writer receiving a SIGPIPE. If the other end can't handle that, be sure to read all the data before @@ -927,7 +943,7 @@ Example: or die "Can't open 'foo' for input: $!"; FILEHANDLE may be an expression whose value can be used as an indirect -filehandle, usually the real filehandle name. +filehandle, usually the real filehandle name or an autovivified handle. =item closedir DIRHANDLE X<closedir> @@ -975,11 +991,11 @@ Omitting the C<continue> section is equivalent to using an empty one, logically enough, so C<next> goes directly back to check the condition at the top of the loop. -If the C<"switch"> feature is enabled, C<continue> is also a -function that exits the current C<when> (or C<default>) block and -falls through to the next one. See L<feature> and -L<perlsyn/"Switch statements"> for more information. - +If the C<"switch"> feature is enabled, C<continue> is also a function that +falls through the current C<when> or C<default> block instead of iterating +a dynamically enclosing C<foreach> or exiting a lexically enclosing C<given>. +See L<feature> and L<perlsyn/"Switch statements"> for more +information. =item cos EXPR X<cos> X<cosine> X<acos> X<arccosine> @@ -987,7 +1003,7 @@ X<cos> X<cosine> X<acos> X<arccosine> =item cos Returns the cosine of EXPR (expressed in radians). If EXPR is omitted, -takes cosine of C<$_>. +takes the cosine of C<$_>. For the inverse cosine operation, you may use the C<Math::Trig::acos()> function, or use this relation: @@ -1002,7 +1018,7 @@ Creates a digest string exactly like the crypt(3) function in the C library (assuming that you actually have a version there that has not been extirpated as a potential munition). -crypt() is a one-way hash function. The PLAINTEXT and SALT is turned +crypt() is a one-way hash function. The PLAINTEXT and SALT are turned into a short string, called a digest, which is returned. The same PLAINTEXT and SALT will always return the same string, but there is no (known) way to get the original PLAINTEXT from the hash. Small @@ -1017,16 +1033,16 @@ having to transmit or store the text itself. An example is checking if a correct password is given. The digest of the password is stored, not the password itself. The user types in a password that is crypt()'d with the same salt as the stored digest. If the two digests -match the password is correct. +match, the password is correct. When verifying an existing digest string you should use the digest as the salt (like C<crypt($plain, $digest) eq $digest>). The SALT used to create the digest is visible as part of the digest. This ensures crypt() will hash the new string with the same salt as the digest. This allows your code to work with the standard L<crypt|/crypt> and -with more exotic implementations. In other words, do not assume -anything about the returned string itself, or how many bytes in the -digest matter. +with more exotic implementations. In other words, assume +nothing about the returned string itself nor about how many bytes +of SALT may matter. Traditionally the result is a string of 13 bytes: two first bytes of the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only @@ -1068,7 +1084,7 @@ back. Look at the L<Digest> module for more robust algorithms. If using crypt() on a Unicode string (which I<potentially> has characters with codepoints above 255), Perl tries to make sense -of the situation by trying to downgrade (a copy of the string) +of the situation by trying to downgrade (a copy of) the string back to an eight-bit byte string before calling crypt() (on that copy). If that works, good. If not, crypt() dies with C<Wide character in crypt>. @@ -1123,6 +1139,12 @@ before you call dbmopen(): dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db") or die "Can't open netscape history file: $!"; +=item default BLOCK + +Within a C<foreach> or a C<given>, a C<default> BLOCK acts like a C<when> +that's always true. Only available after Perl 5.10, and only if the +C<switch> feature has been requested. See L</when>. + =item defined EXPR X<defined> X<undef> X<undefined> @@ -1150,7 +1172,7 @@ makes it spring into existence the first time that it is called; see L<perlsub>. Use of C<defined> on aggregates (hashes and arrays) is deprecated. It -used to report whether memory for that aggregate has ever been +used to report whether memory for that aggregate had ever been allocated. This behavior may disappear in future versions of Perl. You should instead use a simple test for size: @@ -1163,14 +1185,14 @@ purpose. Examples: - print if defined $switch{'D'}; + print if defined $switch{D}; print "$val\n" while defined($val = pop(@ary)); die "Can't readlink $sym: $!" unless defined($value = readlink $sym); sub foo { defined &$bar ? &$bar(@_) : die "No bar"; } $debugging = 0 unless defined $debugging; -Note: Many folks tend to overuse C<defined>, and then are surprised to +Note: Many folks tend to overuse C<defined> and are then surprised to discover that the number C<0> and C<""> (the zero-length string) are, in fact, defined values. For example, if you say @@ -1195,7 +1217,7 @@ deletes the specified elements from that hash so that exists() on that element no longer returns true. Setting a hash element to the undefined value does not remove its key, but deleting it does; see L</exists>. -It returns the value or values deleted in list context, or the last such +In list context, returns the value or values deleted, or the last such element in scalar context. The return list's length always matches that of the argument list: deleting non-existent elements returns the undefined value in their corresponding positions. @@ -1207,7 +1229,7 @@ or splice() for that. However, if all deleted elements fall at the end of an array, the array's size shrinks to the position of the highest element that still tests true for exists(), or to 0 if none do. -B<Be aware> that calling delete on array values is deprecated and likely to +B<WARNING:> Calling delete on array values is deprecated and likely to be removed in a future version of Perl. Deleting from C<%ENV> modifies the environment. Deleting from a hash tied to @@ -1267,7 +1289,7 @@ C<die> raises an exception. Inside an C<eval> the error message is stuffed into C<$@> and the C<eval> is terminated with the undefined value. If the exception is outside of all enclosing C<eval>s, then the uncaught exception prints LIST to C<STDERR> and exits with a non-zero value. If you -need to exit the process with a specific exit code, see L<exit>. +need to exit the process with a specific exit code, see L</exit>. Equivalent examples: @@ -1303,7 +1325,7 @@ This is useful for propagating exceptions: If the output is empty and C<$@> contains an object reference that has a C<PROPAGATE> method, that method will be called with additional file and line number parameters. The return value replaces the value in -C<$@>. i.e., as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> +C<$@>; i.e., as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> were called. If C<$@> is empty then the string C<"Died"> is used. @@ -1351,7 +1373,7 @@ You can arrange for a callback to be run just before the C<die> does its deed, by setting the C<$SIG{__DIE__}> hook. The associated handler is called with the error text and can change the error message, if it sees fit, by calling C<die> again. See -L<perlvar/$SIG{expr}> for details on setting C<%SIG> entries, and +L<perlvar/%SIG> for details on setting C<%SIG> entries, and L<"eval BLOCK"> for some examples. Although this feature was to be run only right before your program was to exit, this is not currently so: the C<$SIG{__DIE__}> hook is currently called @@ -1382,7 +1404,8 @@ See L<perlsyn> for alternative strategies. =item do SUBROUTINE(LIST) X<do> -This form of subroutine call is deprecated. See L<perlsub>. +This form of subroutine call is deprecated. SUBROUTINE can be a bareword, +a scalar variable or a subroutine beginning with C<&>. =item do EXPR X<do> @@ -1397,18 +1420,18 @@ is just like eval `cat stat.pl`; except that it's more efficient and concise, keeps track of the current -filename for error messages, searches the @INC directories, and updates -C<%INC> if the file is found. See L<perlvar/Predefined Names> for these -variables. It also differs in that code evaluated with C<do FILENAME> +filename for error messages, searches the C<@INC> directories, and updates +C<%INC> if the file is found. See L<perlvar/@INC> and L<perlvar/%INC> for +these variables. It also differs in that code evaluated with C<do FILENAME> cannot see lexicals in the enclosing scope; C<eval STRING> does. It's the same, however, in that it does reparse the file every time you call it, so you probably don't want to do this inside a loop. -If C<do> cannot read the file, it returns undef and sets C<$!> to the -error. If C<do> can read the file but cannot compile it, it -returns undef and sets an error message in C<$@>. If the file is -successfully compiled, C<do> returns the value of the last expression -evaluated. +If C<do> can read the file but cannot compile it, it returns C<undef> and sets +an error message in C<$@>. If C<do> cannot read the file, it returns undef +and sets C<$!> to the error. Always check C<$@> first, as compilation +could fail in a way that also sets C<$!>. If the file is successfully +compiled, C<do> returns the value of the last expression evaluated. Inclusion of library modules is better done with the C<use> and C<require> operators, which also do automatic error checking @@ -1458,6 +1481,8 @@ X<each> X<hash, iterator> =item each ARRAY X<array, iterator> +=item each EXPR + When called in list context, returns a 2-element list consisting of the key and value for the next element of a hash, or the index and value for the next element of an array, so that you can iterate over it. When called in @@ -1494,7 +1519,14 @@ but in a different order: print "$key=$value\n"; } -See also C<keys>, C<values> and C<sort>. +Starting with Perl 5.14, C<each> can take a scalar EXPR, which must hold +reference to an unblessed hash or array. The argument will be dereferenced +automatically. This aspect of C<each> is considered highly experimental. +The exact behaviour may change in a future version of Perl. + + while (($key,$value) = each $hashref) { ... } + +See also C<keys>, C<values>, and C<sort>. =item eof FILEHANDLE X<eof> @@ -1505,7 +1537,7 @@ X<end-of-file> =item eof -Returns 1 if the next read on FILEHANDLE will return end of file, or if +Returns 1 if the next read on FILEHANDLE will return end of file I<or> if FILEHANDLE is not open. FILEHANDLE may be an expression whose value gives the real filehandle. (Note that this function actually reads a character and then C<ungetc>s it, so isn't useful in an @@ -1525,8 +1557,8 @@ and if you haven't set C<@ARGV>, will read input from C<STDIN>; see L<perlop/"I/O Operators">. In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to -detect the end of each file, C<eof()> will detect the end of only the -last file. Examples: +detect the end of each file, whereas C<eof()> will detect the end +of the very last file only. Examples: # reset line numbering on each input file while (<>) { @@ -1546,8 +1578,8 @@ last file. Examples: } Practical hint: you almost never need to use C<eof> in Perl, because the -input operators typically return C<undef> when they run out of data, or if -there was an error. +input operators typically return C<undef> when they run out of data or +encounter an error. =item eval EXPR X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute> @@ -1559,7 +1591,7 @@ X<error, handling> X<exception, handling> In the first form, the return value of EXPR is parsed and executed as if it were a little Perl program. The value of the expression (which is itself -determined within scalar context) is first parsed, and if there weren't any +determined within scalar context) is first parsed, and if there were no errors, executed in the lexical context of the current Perl program, so that any variable settings or subroutine and format definitions remain afterwards. Note that the value is parsed every time the C<eval> executes. @@ -1584,9 +1616,12 @@ 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, 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 the empty +executed, C<eval> returns C<undef> in scalar context +or an empty list--or, for syntax errors, a list containing a single +undefined value--in list context, and C<$@> is set to the error +message. The discrepancy in the return values in list context is +considered a bug by some, and will probably be fixed in a future +release. If there was no error, C<$@> is guaranteed to be the empty string. Beware that using C<eval> neither silences Perl from printing warnings to STDERR, nor does it stuff the text of warning messages into C<$@>. To do either of those, you have to use the C<$SIG{__WARN__}> facility, or @@ -1595,7 +1630,7 @@ See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>. Note that, because C<eval> traps otherwise-fatal errors, it is useful for determining whether a particular feature (such as C<socket> or C<symlink>) -is implemented. It is also Perl's exception trapping mechanism, where +is implemented. It is also Perl's exception-trapping mechanism, where the die operator is used to raise exceptions. If you want to trap errors when loading an XS module, some problems with @@ -1666,8 +1701,9 @@ normally you I<would> like to use double quotes, except that in this particular situation, you can just use symbolic references instead, as in case 6. -The assignment to C<$@> occurs before restoration of localised variables, -which means a temporary is required if you want to mask some but not all +Before Perl 5.14, the assignment to C<$@> occurred before restoration +of localised variables, which means that for your code to run on older +versions, a temporary is required if you want to mask some but not all errors: # alter $@ on nefarious repugnancy only @@ -1676,7 +1712,7 @@ errors: { local $@; # protect existing $@ eval { test_repugnancy() }; - # $@ =~ /nefarious/ and die $@; # DOES NOT WORK + # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only $@ =~ /nefarious/ and $e = $@; } die $e if defined $e @@ -1778,7 +1814,7 @@ corresponding value is undefined. print "True\n" if $hash{$key}; exists may also be called on array elements, but its behavior is much less -obvious, and is strongly tied to the use of L</delete> on arrays. B<Be aware> +obvious and is strongly tied to the use of L</delete> on arrays. B<Be aware> that calling exists on array values is deprecated and likely to be removed in a future version of Perl. @@ -1786,7 +1822,7 @@ a future version of Perl. print "Defined\n" if defined $array[$index]; print "True\n" if $array[$index]; -A hash or array element can be true only if it's defined, and defined if +A hash or array element can be true only if it's defined and defined only if it exists, but the reverse doesn't necessarily hold true. Given an expression that specifies the name of a subroutine, @@ -1855,7 +1891,8 @@ which can be trapped by an C<eval>. The exit() function does not always exit immediately. It calls any defined C<END> routines first, but these C<END> routines may not themselves abort the exit. Likewise any object destructors that need to -be called are called before the real exit. If this is a problem, you +be called are called before the real exit. C<END> routines and destructors +can change the exit status by modifying C<$?>. If this is a problem, you can call C<POSIX:_exit($status)> to avoid END and destructor processing. See L<perlmod> for details. @@ -1908,7 +1945,11 @@ on your own, though. X<fileno> Returns the file descriptor for a filehandle, or undefined if the -filehandle is not open. This is mainly useful for constructing +filehandle is not open. If there is no real file descriptor at the OS +level, as can happen with filehandles connected to memory objects via +C<open> with a reference for the third argument, -1 is returned. + +This is mainly useful for constructing bitmaps for C<select> and low-level POSIX tty-handling operations. If FILEHANDLE is an expression, the value is taken as an indirect filehandle, generally its name. @@ -1920,25 +1961,21 @@ same underlying descriptor: print "THIS and THAT are dups\n"; } -(Filehandles connected to memory objects via new features of C<open> may -return undefined even though they are open.) - - =item flock FILEHANDLE,OPERATION X<flock> X<lock> X<locking> Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true for success, false on failure. Produces a fatal error if used on a machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3). -C<flock> is Perl's portable file locking interface, although it locks +C<flock> is Perl's portable file-locking interface, although it locks entire files only, not records. Two potentially non-obvious but traditional C<flock> semantics are that it waits indefinitely until the lock is granted, and that its locks -B<merely advisory>. Such discretionary locks are more flexible, but offer -fewer guarantees. This means that programs that do not also use C<flock> -may modify files locked with C<flock>. See L<perlport>, -your port's specific documentation, or your system-specific local manpages +are B<merely advisory>. Such discretionary locks are more flexible, but +offer fewer guarantees. This means that programs that do not also use +C<flock> may modify files locked with C<flock>. See L<perlport>, +your port's specific documentation, and your system-specific local manpages for details. It's best to assume traditional behavior if you're writing portable programs. (But if you're not, you should as always feel perfectly free to write for your own system's idiosyncrasies (sometimes called @@ -1947,11 +1984,11 @@ in the way of your getting your job done.) OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but -you can use the symbolic names if you import them from the Fcntl module, -either individually, or as a group using the ':flock' tag. LOCK_SH +you can use the symbolic names if you import them from the L<Fcntl> module, +either individually, or as a group using the C<:flock> tag. LOCK_SH requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN releases a previously requested lock. If LOCK_NB is bitwise-or'ed with -LOCK_SH or LOCK_EX then C<flock> returns immediately rather than blocking +LOCK_SH or LOCK_EX, then C<flock> returns immediately rather than blocking waiting for the lock; check the return status to see if you got it. To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE @@ -1972,7 +2009,7 @@ network; you would need to use the more system-specific C<fcntl> for that. If you like you can force Perl to ignore your system's flock(2) function, and so provide its own fcntl(2)-based emulation, by passing the switch C<-Ud_flock> to the F<Configure> program when you configure -Perl. +and build a new Perl. Here's a mailbox appender for BSD systems. @@ -2071,6 +2108,10 @@ Be careful if you put double quotes around the picture, because an C<@> character may be taken to mean the beginning of an array name. C<formline> always returns true. See L<perlform> for other examples. +If you are trying to use this instead of C<write> to capture the output, +you may find it easier to open a filehandle to a scalar +(C<< open $fh, ">", \$output >>) and write to that instead. + =item getc FILEHANDLE X<getc> X<getchar> X<character> X<file, read> @@ -2105,7 +2146,7 @@ is left as an exercise to the reader. The C<POSIX::getattr> function can do this more portably on systems purporting POSIX compliance. See also the C<Term::ReadKey> -module from your nearest CPAN site; details on CPAN can be found on +module from your nearest CPAN site; details on CPAN can be found under L<perlmodlib/CPAN>. =item getlogin @@ -2123,7 +2164,8 @@ secure as C<getpwuid>. =item getpeername SOCKET X<getpeername> X<peer> -Returns the packed sockaddr address of other end of the SOCKET connection. +Returns the packed sockaddr address of the other end of the SOCKET +connection. use Socket; $hersockaddr = getpeername(SOCK); @@ -2137,8 +2179,8 @@ X<getpgrp> X<group> Returns the current process group for the specified PID. Use a PID of C<0> to get the current process group for the current process. Will raise an exception if used on a machine that -doesn't implement getpgrp(2). If PID is omitted, returns process -group of current process. Note that the POSIX version of C<getpgrp> +doesn't implement getpgrp(2). If PID is omitted, returns the process +group of the current process. Note that the POSIX version of C<getpgrp> does not accept a PID argument, so only C<PID==0> is truly portable. =item getppid @@ -2246,7 +2288,7 @@ information pertaining to the user. Beware, however, that in many system users are able to change this information and therefore it cannot be trusted and therefore the $gcos is tainted (see L<perlsec>). The $passwd and $shell, user's encrypted password and -login shell, are also tainted, because of the same reason. +login shell, are also tainted, for the same reason. In scalar context, you get the name, unless the function was a lookup by name, in which case you get the other thing, whatever it is. @@ -2270,7 +2312,7 @@ field may be $change or $age, fields that have to do with password aging. In some systems the $comment field may be $class. The $expire field, if present, encodes the expiration period of the account or the password. For the availability and the exact meaning of these fields -in your system, please consult your getpwnam(3) documentation and your +in your system, please consult getpwnam(3) and your system's F<pwd.h> file. You can also find out from within Perl what your $quota and $comment fields mean and whether you have the $expire field by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>, @@ -2279,10 +2321,10 @@ files are supported only if your vendor has implemented them in the intuitive fashion that calling the regular C library routines gets the shadow versions if you're running under privilege or if there exists the shadow(3) functions as found in System V (this includes Solaris -and Linux.) Those systems that implement a proprietary shadow password +and Linux). Those systems that implement a proprietary shadow password facility are unlikely to be supported. -The $members value returned by I<getgr*()> is a space separated list of +The $members value returned by I<getgr*()> is a space-separated list of the login names of the members of the group. For the I<gethost*()> functions, if the C<h_errno> variable is supported in @@ -2327,7 +2369,7 @@ for each field. For example: use User::pwent; $is_his = (stat($filename)->uid == pwent($whoever)->uid); -Even though it looks like they're the same method calls (uid), +Even though it looks as though they're the same method calls (uid), they aren't, because a C<File::stat> object is different from a C<User::pwent> object. @@ -2359,12 +2401,12 @@ number of TCP, which you can get using C<getprotobyname>. The function returns a packed string representing the requested socket option, or C<undef> on error, with the reason for the error placed in -C<$!>). Just what is in the packed string depends on LEVEL and OPTNAME; +C<$!>. Just what is in the packed string depends on LEVEL and OPTNAME; consult getsockopt(2) for details. A common case is that the option is an integer, in which case the result is a packed integer, which you can decode using C<unpack> with the C<i> (or C<I>) format. -An example to test whether Nagle's algorithm is turned on on a socket: +Here's an example to test whether Nagle's algorithm is enabled on a socket: use Socket qw(:all); @@ -2377,6 +2419,30 @@ An example to test whether Nagle's algorithm is turned on on a socket: print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n"; +=item given EXPR BLOCK +X<given> + +=item given BLOCK + +C<given> is analogous to the C<switch> keyword in other languages. C<given> +and C<when> are used in Perl to implement C<switch>/C<case> like statements. +Only available after Perl 5.10. For example: + + use v5.10; + given ($fruit) { + when (/apples?/) { + print "I like apples." + } + when (/oranges?/) { + print "I don't like oranges." + } + default { + print "I don't like anything" + } + } + +See L<perlsyn/"Switch statements"> for detailed information. + =item glob EXPR X<glob> X<wildcard> X<filename, expansion> X<expand> @@ -2393,7 +2459,7 @@ more detail in L<perlop/"I/O Operators">. Note that C<glob> splits its arguments on whitespace and treats each segment as separate pattern. As such, C<glob("*.c *.h")> matches all files with a F<.c> or F<.h> extension. The expression -C<glob(".* *")> matchs all files in the current working directory. +C<glob(".* *")> matches all files in the current working directory. If non-empty braces are the only wildcard characters used in the C<glob>, no filenames are matched, but potentially many strings @@ -2414,8 +2480,8 @@ X<gmtime> X<UTC> X<Greenwich> Works just like L<localtime> but the returned values are localized for the standard Greenwich time zone. -Note: when called in list context, $isdst, the last value -returned by gmtime is always C<0>. There is no +Note: When called in list context, $isdst, the last value +returned by gmtime, is always C<0>. There is no Daylight Saving Time in GMT. See L<perlport/gmtime> for portability concerns. @@ -2443,6 +2509,10 @@ necessarily recommended if you're optimizing for maintainability: goto ("FOO", "BAR", "GLARCH")[$i]; +As shown in this example, C<goto-EXPR> is exempt from the "looks like a +function" rule. A pair of parentheses following it does not (necessarily) +delimit its argument. C<goto("NE")."XT"> is equivalent to C<goto NEXT>. + Use of C<goto-LABEL> or C<goto-EXPR> to jump into a construct is deprecated and will issue a warning. Even then, it may not be used to go into any construct that requires initialization, such as a @@ -2462,7 +2532,7 @@ After the C<goto>, not even C<caller> will be able to tell that this routine was called first. NAME needn't be the name of a subroutine; it can be a scalar variable -containing a code reference, or a block that evaluates to a code +containing a code reference or a block that evaluates to a code reference. =item grep BLOCK LIST @@ -2515,7 +2585,7 @@ L</oct>.) If EXPR is omitted, uses C<$_>. Hex strings may only represent integers. Strings that would cause integer overflow trigger a warning. Leading whitespace is not stripped, unlike oct(). To present something as hex, look into L</printf>, -L</sprintf>, or L</unpack>. +L</sprintf>, and L</unpack>. =item import LIST X<import> @@ -2607,6 +2677,8 @@ X<keys> X<key> =item keys ARRAY +=item keys EXPR + Returns a list consisting of all the keys of the named hash, or the indices of an array. (In scalar context, returns the number of keys or indices.) @@ -2614,11 +2686,11 @@ The keys of a hash are returned in an apparently random order. The actual random order is subject to change in future versions of Perl, but it is guaranteed to be the same order as either the C<values> or C<each> function produces (given that the hash has not been modified). Since -Perl 5.8.1 the ordering is different even between different runs of +Perl 5.8.1 the ordering can be different even between different runs of Perl for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">). -As a side effect, calling keys() resets the HASH or ARRAY's internal iterator +As a side effect, calling keys() resets the internal interator of the HASH or ARRAY (see L</each>). In particular, calling keys() in void context resets the iterator with no other overhead. @@ -2662,7 +2734,15 @@ C<keys> in this way (but you needn't worry about doing this by accident, as trying has no effect). C<keys @array> in an lvalue context is a syntax error. -See also C<each>, C<values> and C<sort>. +Starting with Perl 5.14, C<keys> can take a scalar EXPR, which must contain +a reference to an unblessed hash or array. The argument will be +dereferenced automatically. This aspect of C<keys> is considered highly +experimental. The exact behaviour may change in a future version of Perl. + + for (keys $hashref) { ... } + for (keys $obj->get_arrayref) { ... } + +See also C<each>, C<values>, and C<sort>. =item kill SIGNAL, LIST X<kill> X<signal> @@ -2707,7 +2787,7 @@ C<continue> block, if any, is not executed: } C<last> cannot be used to exit a block that returns a value such as -C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit +C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit a grep() or map() operation. Note that a block by itself is semantically identical to a loop @@ -2749,7 +2829,8 @@ respectively. =item Otherwise, If EXPR has the UTF8 flag set If the current package has a subroutine named C<ToLower>, it will be used to -change the case (See L<perlunicode/User-Defined Case Mappings>.) +change the case +(See L<perlunicode/"User-Defined Case Mappings (for serious hackers only)">.) Otherwise Unicode semantics are used for the case change. =item Otherwise, if C<use locale> is in effect @@ -2759,7 +2840,7 @@ Respects current LC_CTYPE locale. See L<perllocale>. =item Otherwise, if C<use feature 'unicode_strings'> is in effect: Unicode semantics are used for the case change. Any subroutine named -C<ToLower> will not be used. +C<ToLower> will be ignored. =item Otherwise: @@ -2789,7 +2870,7 @@ double-quoted strings. If EXPR is omitted, uses C<$_>. -This function behaves the same way under various pragma, such as in a locale, +This function behaves the same way under various pragmata, such as in a locale, as L</lc> does. =item length EXPR @@ -2798,7 +2879,8 @@ X<length> X<size> =item length Returns the length in I<characters> of the value of EXPR. If EXPR is -omitted, returns length of C<$_>. If EXPR is undefined, returns C<undef>. +omitted, returns the length of C<$_>. If EXPR is undefined, returns +C<undef>. This function cannot be used on an entire array or hash to find out how many elements these have. For that, use C<scalar @array> and C<scalar keys @@ -2851,19 +2933,19 @@ follows: ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time); -All list elements are numeric, and come straight out of the C `struct +All list elements are numeric and come straight out of the C `struct tm'. C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours of the specified time. -C<$mday> is the day of the month, and C<$mon> is the month itself, in -the range C<0..11> with 0 indicating January and 11 indicating December. +C<$mday> is the day of the month and C<$mon> the month in +the range C<0..11>, with 0 indicating January and 11 indicating December. This makes it easy to get a month name from a list: my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ); print "$abbr[$mon] $mday"; # $mon=9, $mday=18 gives "Oct 18" -C<$year> is the number of years since 1900, not just the last two digits +C<$year> is the number of years since 1900, B<not> just the last two digits of the year. That is, C<$year> is C<123> in year 2023. The proper way to get a 4-digit year is simply: @@ -2872,7 +2954,7 @@ to get a 4-digit year is simply: Otherwise you create non-Y2K-compliant programs--and you wouldn't want to do that, would you? -To get the last two digits of the year (e.g., '01' in 2001) do: +To get the last two digits of the year (e.g., "01" in 2001) do: $year = sprintf("%02d", $year % 100); @@ -2890,13 +2972,13 @@ In scalar context, C<localtime()> returns the ctime(3) value: $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994" -This scalar value is B<not> locale dependent but is a Perl builtin. For GMT +This scalar value is B<not> locale-dependent but is a Perl builtin. For GMT instead of local time use the L</gmtime> builtin. See also the -C<Time::Local> module (to convert the second, minutes, hours, ... back to +C<Time::Local> module (for converting seconds, minutes, hours, and such back to the integer value returned by time()), and the L<POSIX> module's strftime(3) and mktime(3) functions. -To get somewhat similar but locale dependent date strings, set up your +To get somewhat similar but locale-dependent date strings, set up your locale environment variables appropriately (please see L<perllocale>) and try for example: @@ -2910,7 +2992,7 @@ and the month of the year, may not necessarily be three characters wide. See L<perlport/localtime> for portability concerns. -The L<Time::gmtime> and L<Time::localtime> modules provides a convenient, +The L<Time::gmtime> and L<Time::localtime> modules provide a convenient, by-name access mechanism to the gmtime() and localtime() functions, respectively. @@ -2920,7 +3002,7 @@ L<DateTime> module on CPAN. =item lock THING X<lock> -This function places an advisory lock on a shared variable, or referenced +This function places an advisory lock on a shared variable or referenced object contained in I<THING> until the lock goes out of scope. lock() is a "weak keyword" : this means that if you've defined a function @@ -2934,7 +3016,8 @@ X<log> X<logarithm> X<e> X<ln> X<base> =item log Returns the natural logarithm (base I<e>) of EXPR. If EXPR is omitted, -returns log of C<$_>. To get the log of another base, use basic algebra: +returns the log of C<$_>. To get the +log of another base, use basic algebra: The base-N log of a number is equal to the natural log of that number divided by the natural log of N. For example: @@ -2974,9 +3057,27 @@ total number of elements so generated. Evaluates BLOCK or EXPR in list context, so each element of LIST may produce zero, one, or more elements in the returned value. - @chars = map(chr, @nums); + @chars = map(chr, @numbers); + +translates a list of numbers to the corresponding characters. + + my @squares = map { $_ * $_ } @numbers; -translates a list of numbers to the corresponding characters. And +translates a list of numbers to their squared values. + + my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers; + +shows that number of returned elements can differ from the number of +input elements. To omit an element, return an empty list (). +This could also be achieved by writing + + my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers; + +which makes the intention more clear. + +Map always returns a list, which can be +assigned to a hash such that the elements +become key/value pairs. See L<perldata> for more details. %hash = map { get_a_key_for($_) => $_ } @array; @@ -3031,12 +3132,12 @@ X<mkdir> X<md> X<directory, create> Creates the directory specified by FILENAME, with permissions specified by MASK (as modified by C<umask>). If it succeeds it -returns true, otherwise it returns false and sets C<$!> (errno). -If omitted, MASK defaults to 0777. If omitted, FILENAME defaults -to C<$_>. +returns true; otherwise it returns false and sets C<$!> (errno). +MASK defaults to 0777 if omitted, and FILENAME defaults +to C<$_> if omitted. -In general, it is better to create directories with permissive MASK, -and let the user modify that with their C<umask>, than it is to supply +In general, it is better to create directories with a permissive MASK +and let the user modify that with their C<umask> than it is to supply a restrictive MASK and give the user no way to be more permissive. The exceptions to this rule are when the file or directory should be kept private (mail files, for instance). The perlfunc(1) entry on @@ -3061,14 +3162,16 @@ first to get the correct constant definitions. If CMD is C<IPC_STAT>, then ARG must be a variable that will hold the returned C<msqid_ds> structure. Returns like C<ioctl>: the undefined value for error, C<"0 but true"> for zero, or the actual return value otherwise. See also -L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation. +L<perlipc/"SysV IPC"> and the documentation for C<IPC::SysV> and +C<IPC::Semaphore>. =item msgget KEY,FLAGS X<msgget> Calls the System V IPC function msgget(2). Returns the message queue -id, or the undefined value if there is an error. See also -L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation. +id, or C<undef> on error. See also +L<perlipc/"SysV IPC"> and the documentation for C<IPC::SysV> and +C<IPC::Msg>. =item msgrcv ID,VAR,SIZE,TYPE,FLAGS X<msgrcv> @@ -3078,19 +3181,19 @@ message queue ID into variable VAR with a maximum message size of SIZE. Note that when a message is received, the message type as a native long integer will be the first thing in VAR, followed by the actual message. This packing may be opened with C<unpack("l! a*")>. -Taints the variable. Returns true if successful, or false if there is -an error. See also L<perlipc/"SysV IPC">, C<IPC::SysV>, and -C<IPC::SysV::Msg> documentation. +Taints the variable. Returns true if successful, false +on error. See also L<perlipc/"SysV IPC"> and the documentation for +C<IPC::SysV> and C<IPC::SysV::Msg>. =item msgsnd ID,MSG,FLAGS X<msgsnd> Calls the System V IPC function msgsnd to send the message MSG to the message queue ID. MSG must begin with the native long integer message -type, and be followed by the length of the actual message, and finally +type, be followed by the length of the actual message, and then finally the message itself. This kind of packing can be achieved with C<pack("l! a*", $type, $message)>. Returns true if successful, -or false if there is an error. See also C<IPC::SysV> +false on error. See also the C<IPC::SysV> and C<IPC::SysV::Msg> documentation. =item my EXPR @@ -3107,7 +3210,7 @@ enclosing block, file, or C<eval>. If more than one value is listed, the list must be placed in parentheses. The exact semantics and interface of TYPE and ATTRS are still -evolving. TYPE is currently bound to the use of C<fields> pragma, +evolving. TYPE is currently bound to the use of the C<fields> pragma, and attributes are handled using the C<attributes> pragma, or starting from Perl 5.8.0 also via the C<Attribute::Handlers> module. See L<perlsub/"Private Variables via my()"> for details, and L<fields>, @@ -3131,7 +3234,7 @@ executed even on discarded lines. If LABEL is omitted, the command refers to the innermost enclosing loop. C<next> cannot be used to exit a block which returns a value such as -C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit +C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit a grep() or map() operation. Note that a block by itself is semantically identical to a loop @@ -3199,67 +3302,66 @@ FILEHANDLE. Simple examples to open a file for reading: - open(my $fh, '<', "input.txt") or die $!; + open(my $fh, "<", "input.txt") + or die "cannot open < input.txt: $!"; and for writing: - open(my $fh, '>', "output.txt") or die $!; + open(my $fh, ">", "output.txt") + or die "cannot open > output.txt: $!"; (The following is a comprehensive reference to open(): for a gentler introduction you may consider L<perlopentut>.) -If FILEHANDLE is an undefined scalar variable (or array or hash element) -the variable is assigned a reference to a new anonymous filehandle, -otherwise if FILEHANDLE is an expression, its value is used as the name of -the real filehandle wanted. (This is considered a symbolic reference, so -C<use strict 'refs'> should I<not> be in effect.) - -If EXPR is omitted, the scalar variable of the same name as the -FILEHANDLE contains the filename. (Note that lexical variables--those -declared with C<my>--will not work for this purpose; so if you're -using C<my>, specify EXPR in your call to open.) - -If three or more arguments are specified then the mode of opening and -the filename are separate. If MODE is C<< '<' >> or nothing, the file -is opened for input. If MODE is C<< '>' >>, the file is truncated and -opened for output, being created if necessary. If MODE is C<<< '>>' >>>, -the file is opened for appending, again being created if necessary. - -You can put a C<'+'> in front of the C<< '>' >> or C<< '<' >> to +If FILEHANDLE is an undefined scalar variable (or array or hash element), a +new filehandle is autovivified, meaning that the variable is assigned a +reference to a newly allocated anonymous filehandle. Otherwise if +FILEHANDLE is an expression, its value is the real filehandle. (This is +considered a symbolic reference, so C<use strict "refs"> should I<not> be +in effect.) + +If EXPR is omitted, the global (package) scalar variable of the same +name as the FILEHANDLE contains the filename. (Note that lexical +variables--those declared with C<my> or C<state>--will not work for this +purpose; so if you're using C<my> or C<state>, specify EXPR in your +call to open.) + +If three (or more) arguments are specified, the open mode (including +optional encoding) in the second argument are distinct from the filename in +the third. If MODE is C<< < >> or nothing, the file is opened for input. +If MODE is C<< > >>, the file is opened for output, with existing files +first being truncated ("clobbered") and nonexisting files newly created. +If MODE is C<<< >> >>>, the file is opened for appending, again being +created if necessary. + +You can put a C<+> in front of the C<< > >> or C<< < >> to indicate that you want both read and write access to the file; thus -C<< '+<' >> is almost always preferred for read/write updates--the -C<< '+>' >> mode would clobber the file first. You can't usually use +C<< +< >> is almost always preferred for read/write updates--the +C<< +> >> mode would clobber the file first. You cant usually use either read-write mode for updating textfiles, since they have -variable length records. See the B<-i> switch in L<perlrun> for a +variable-length records. See the B<-i> switch in L<perlrun> for a better approach. The file is created with permissions of C<0666> modified by the process's C<umask> value. -These various prefixes correspond to the fopen(3) modes of C<'r'>, -C<'r+'>, C<'w'>, C<'w+'>, C<'a'>, and C<'a+'>. +These various prefixes correspond to the fopen(3) modes of C<r>, +C<r+>, C<w>, C<w+>, C<a>, and C<a+>. -In the two-argument (and one-argument) form of the call, the mode and -filename should be concatenated (in that order), possibly separated by -spaces. You may omit the mode in these forms when that mode is -C<< '<' >>. +In the one- and two-argument forms of the call, the mode and filename +should be concatenated (in that order), preferably separated by white +space. You can--but shouldn't--omit the mode in these forms when that mode +is C<< < >>. It is always safe to use the two-argument form of C<open> if +the filename argument is a known literal. -If the filename begins with C<'|'>, the filename is interpreted as a -command to which output is to be piped, and if the filename ends with a -C<'|'>, the filename is interpreted as a command that pipes output to -us. See L<perlipc/"Using open() for IPC"> -for more examples of this. (You are not allowed to C<open> to a command -that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>, -and L<perlipc/"Bidirectional Communication with Another Process"> -for alternatives.) - -For three or more arguments if MODE is C<'|-'>, the filename is +For three or more arguments if MODE is C<|->, the filename is interpreted as a command to which output is to be piped, and if MODE -is C<'-|'>, the filename is interpreted as a command that pipes +is C<-|>, the filename is interpreted as a command that pipes output to us. In the two-argument (and one-argument) form, one should -replace dash (C<'-'>) with the command. +replace dash (C<->) with the command. See L<perlipc/"Using open() for IPC"> for more examples of this. (You are not allowed to C<open> to a command that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>, and -L<perlipc/"Bidirectional Communication"> for alternatives.) +L<perlipc/"Bidirectional Communication with Another Process"> for +alternatives.) In the form of pipe opens taking three or more arguments, if LIST is specified (extra arguments after the command name) then LIST becomes arguments @@ -3268,18 +3370,18 @@ C<open> with more than three arguments for non-pipe modes is not yet defined, but experimental "layers" may give extra LIST arguments meaning. -In the two-argument (and one-argument) form, opening C<< '<-' >> -or C<'-'> opens STDIN and opening C<< '>-' >> opens STDOUT. +In the two-argument (and one-argument) form, opening C<< <- >> +or C<-> opens STDIN and opening C<< >- >> opens STDOUT. -You may use the three-argument form of open to specify I/O layers -(sometimes referred to as "disciplines") to apply to the handle +You may (and usually should) use the three-argument form of open to specify +I/O layers (sometimes referred to as "disciplines") to apply to the handle that affect how the input and output are processed (see L<open> and L<PerlIO> for more details). For example: open(my $fh, "<:encoding(UTF-8)", "filename") || die "can't open UTF-8 encoded filename: $!"; -opens the UTF-8 encoded file containing Unicode characters; +opens the UTF8-encoded file containing Unicode characters; see L<perluniintro>. Note that if layers are specified in the three-argument form, then default layers stored in ${^OPEN} (see L<perlvar>; usually set by the B<open> pragma or the switch B<-CioD>) are ignored. @@ -3303,43 +3405,44 @@ where you want to format a suitable error message (but there are modules that can help with that problem)) always check the return value from opening a file. -As a special case the 3-arg form with a read/write mode and the third +As a special case the three-argument form with a read/write mode and the third argument being C<undef>: open(my $tmp, "+>", undef) or die ... -opens a filehandle to an anonymous temporary file. Also using "+<" +opens a filehandle to an anonymous temporary file. Also using C<< +< >> works for symmetry, but you really should consider writing something to the temporary file first. You will need to seek() to do the reading. Since v5.8.0, Perl has built using PerlIO by default. Unless you've -changed this (i.e., Configure -Uuseperlio), you can open filehandles -directly to Perl scalars via: +changed this (such as building Perl with C<Configure -Uuseperlio>), you can +open filehandles directly to Perl scalars via: - open($fh, '>', \$variable) || .. + open($fh, ">", \$variable) || .. To (re)open C<STDOUT> or C<STDERR> as an in-memory file, close it first: close STDOUT; - open STDOUT, '>', \$variable or die "Can't open STDOUT: $!"; + open(STDOUT, ">", \$variable) + or die "Can't open STDOUT: $!"; General examples: $ARTICLE = 100; - open ARTICLE or die "Can't find article $ARTICLE: $!\n"; + open(ARTICLE) or die "Can't find article $ARTICLE: $!\n"; while (<ARTICLE>) {... - open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved) + open(LOG, ">>/usr/spool/news/twitlog"); # (log is reserved) # if the open fails, output is discarded - open(my $dbase, '+<', 'dbase.mine') # open for update + open(my $dbase, "+<", "dbase.mine") # open for update or die "Can't open 'dbase.mine' for update: $!"; - open(my $dbase, '+<dbase.mine') # ditto + open(my $dbase, "+<dbase.mine") # ditto or die "Can't open 'dbase.mine' for update: $!"; - open(ARTICLE, '-|', "caesar <$article") # decrypt article + open(ARTICLE, "-|", "caesar <$article") # decrypt article or die "Can't start caesar: $!"; open(ARTICLE, "caesar <$article |") # ditto @@ -3349,20 +3452,20 @@ General examples: or die "Can't start sort: $!"; # in-memory files - open(MEMORY,'>', \$var) + open(MEMORY, ">", \$var) or die "Can't open memory file: $!"; print MEMORY "foo!\n"; # output will appear in $var # process argument list of files along with any includes foreach $file (@ARGV) { - process($file, 'fh00'); + process($file, "fh00"); } sub process { my($filename, $input) = @_; $input++; # this is a string increment - unless (open($input, $filename)) { + unless (open($input, "<", $filename)) { print STDERR "Can't open $filename: $!\n"; return; } @@ -3380,24 +3483,24 @@ General examples: 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 +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 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 -of IO buffers.) If you use the 3-arg form then you can pass either a -number, the name of a filehandle or the normal "reference to a glob". +of IO buffers.) If you use the three-argument form, then you can pass either a +number, the name of a filehandle, or the normal "reference to a glob". Here is a script that saves, redirects, and restores C<STDOUT> and C<STDERR> using various methods: #!/usr/bin/perl - open my $oldout, ">&STDOUT" or die "Can't dup STDOUT: $!"; - open OLDERR, ">&", \*STDERR or die "Can't dup STDERR: $!"; + open(my $oldout, ">&STDOUT") or die "Can't dup STDOUT: $!"; + open(OLDERR, ">&", \*STDERR) or die "Can't dup STDERR: $!"; - open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!"; - open STDERR, ">&STDOUT" or die "Can't dup STDOUT: $!"; + open(STDOUT, '>', "foo.out") or die "Can't redirect STDOUT: $!"; + open(STDERR, ">&STDOUT") or die "Can't dup STDOUT: $!"; select STDERR; $| = 1; # make unbuffered select STDOUT; $| = 1; # make unbuffered @@ -3405,8 +3508,8 @@ C<STDERR> using various methods: print STDOUT "stdout 1\n"; # this works for print STDERR "stderr 1\n"; # subprocesses too - open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!"; - open STDERR, ">&OLDERR" or die "Can't dup OLDERR: $!"; + open(STDOUT, ">&", $oldout) or die "Can't dup \$oldout: $!"; + open(STDERR, ">&OLDERR") or die "Can't dup OLDERR: $!"; print STDOUT "stdout 2\n"; print STDERR "stderr 2\n"; @@ -3435,26 +3538,47 @@ or Being parsimonious on filehandles is also useful (besides being parsimonious) for example when something is dependent on file descriptors, like for example locking using flock(). If you do just -C<< open(A, '>>&B') >>, the filehandle A will not have the same file -descriptor as B, and therefore flock(A) will not flock(B), and vice -versa. But with C<< open(A, '>>&=B') >> the filehandles will share -the same file descriptor. - -Note that if you are using Perls older than 5.8.0, Perl will be using -the standard C libraries' fdopen() to implement the "=" functionality. -On many Unix systems fdopen() fails when file descriptors exceed a -certain value, typically 255. For Perls 5.8.0 and later, PerlIO is -most often the default. - -You can see whether Perl has been compiled with PerlIO or not by -running C<perl -V> and looking for C<useperlio=> line. If C<useperlio> -is C<define>, you have PerlIO, otherwise you don't. - -If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'> -with 2-arguments (or 1-argument) form of open(), then -there is an implicit fork done, and the return value of open is the pid -of the child within the parent process, and C<0> within the child -process. (Use C<defined($pid)> to determine whether the open was successful.) +C<< open(A, ">>&B") >>, the filehandle A will not have the same file +descriptor as B, and therefore flock(A) will not flock(B) nor vice +versa. But with C<< open(A, ">>&=B") >>, the filehandles will share +the same underlying system file descriptor. + +Note that under Perls older than 5.8.0, Perl uses the standard C library's' +fdopen() to implement the C<=> functionality. On many Unix systems, +fdopen() fails when file descriptors exceed a certain value, typically 255. +For Perls 5.8.0 and later, PerlIO is (most often) the default. + +You can see whether your Perl was built with PerlIO by running C<perl -V> +and looking for the C<useperlio=> line. If C<useperlio> is C<define>, you +have PerlIO; otherwise you don't. + +If you open a pipe on the command C<-> (that is, specify either C<|-> or C<-|> +with the one- or two-argument forms of C<open>), +an implicit C<fork> is done, so C<open> returns twice: in the parent +process it returns the pid +of the child process, and in the child process it returns (a defined) C<0>. +Use C<defined($pid)> or C<//> to determine whether the open was successful. + +For example, use either + + $child_pid = open(FROM_KID, "|-") // die "can't fork: $!"; + +or + $child_pid = open(TO_KID, "|-") // die "can't fork: $!"; + +followed by + + if ($child_pid) { + # am the parent: + # either write TO_KID or else read FROM_KID + ... + wait $child_pid; + } else { + # am the child; use STDIN/STDOUT normally + ... + exit; + } + The filehandle behaves normally for the parent, but I/O to that filehandle is piped from/to the STDOUT/STDIN of the child process. In the child process, the filehandle isn't opened--I/O happens from/to @@ -3463,22 +3587,29 @@ piped open when you want to exercise more control over just how the pipe command gets executed, such as when running setuid and you don't want to have to scan shell commands for metacharacters. -The following triples are more or less equivalent: +The following blocks are more or less equivalent: open(FOO, "|tr '[a-z]' '[A-Z]'"); - open(FOO, '|-', "tr '[a-z]' '[A-Z]'"); - open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]'; - open(FOO, '|-', "tr", '[a-z]', '[A-Z]'); + open(FOO, "|-", "tr '[a-z]' '[A-Z]'"); + open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]'; + open(FOO, "|-", "tr", '[a-z]', '[A-Z]'); open(FOO, "cat -n '$file'|"); - open(FOO, '-|', "cat -n '$file'"); - open(FOO, '-|') || exec 'cat', '-n', $file; - open(FOO, '-|', "cat", '-n', $file); + open(FOO, "-|", "cat -n '$file'"); + open(FOO, "-|") || exec "cat", "-n", $file; + open(FOO, "-|", "cat", "-n", $file); -The last example in each block shows the pipe as "list form", which is +The last two examples in each block show the pipe as "list form", which is not yet supported on all platforms. A good rule of thumb is that if -your platform has true C<fork()> (in other words, if your platform is -Unix) you can use the list form. +your platform has a real C<fork()> (in other words, if your platform is +Unix, including Linux and MacOS X), you can use the list form. You would +want to use the list form of the pipe so you can pass literal arguments +to the command without risk of the shell interpreting any shell metacharacters +in them. However, this also bars you from opening pipes to commands +that intentionally contain shell metacharacters, such as: + + open(FOO, "|cat -n | expand -4 | lpr") + // die "Can't open pipeline to lpr: $!"; See L<perlipc/"Safe Pipe Opens"> for more examples of this. @@ -3490,14 +3621,14 @@ of C<IO::Handle> on any open handles. On systems that support a close-on-exec flag on files, the flag will be set for the newly opened file descriptor as determined by the value -of $^F. See L<perlvar/$^F>. +of C<$^F>. See L<perlvar/$^F>. Closing any piped filehandle causes the parent process to wait for the -child to finish, and returns the status value in C<$?> and +child to finish, then returns the status value in C<$?> and C<${^CHILD_ERROR_NATIVE}>. -The filename passed to 2-argument (or 1-argument) form of open() will -have leading and trailing whitespace deleted, and the normal +The filename passed to the one- and two-argument forms of open() will +have leading and trailing whitespace deleted and normal redirection characters honored. This property, known as "magic open", can often be used to good effect. A user could specify a filename of F<"rsh cat file |">, or you could change certain filenames as needed: @@ -3505,33 +3636,36 @@ F<"rsh cat file |">, or you could change certain filenames as needed: $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/; open(FH, $filename) or die "Can't open $filename: $!"; -Use 3-argument form to open a file with arbitrary weird characters in it, +Use the three-argument form to open a file with arbitrary weird characters in it, - open(FOO, '<', $file); + open(FOO, "<", $file) + || die "can't open < $file: $!"; otherwise it's necessary to protect any leading and trailing whitespace: $file =~ s#^(\s)#./$1#; - open(FOO, "< $file\0"); + open(FOO, "< $file\0") + || die "open failed: $!"; (this may not work on some bizarre filesystems). One should -conscientiously choose between the I<magic> and 3-arguments form +conscientiously choose between the I<magic> and I<three-argument> form of open(): - open IN, $ARGV[0]; + open(IN, $ARGV[0]) || die "can't open $ARGV[0]: $!"; will allow the user to specify an argument of the form C<"rsh cat file |">, but will not work on a filename that happens to have a trailing space, while - open IN, '<', $ARGV[0]; + open(IN, "<", $ARGV[0]) + || die "can't open < $ARGV[0]: $!"; will have exactly the opposite restrictions. 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 -another way to protect your filenames from interpretation. For example: +should use the C<sysopen> function, which involves no such magic (but may +use subtly different filemodes than Perl open(), which is mapped to C +fopen()). This is another way to protect your filenames from +interpretation. For example: use IO::Handle; sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL) @@ -3543,22 +3677,32 @@ another way to protect your filenames from interpretation. For example: Using the constructor from the C<IO::Handle> package (or one of its subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous -filehandles that have the scope of whatever variables hold references to -them, and automatically close whenever and however you leave that scope: +filehandles that have the scope of the variables used to hold them, then +automatically (but silently) close once their reference counts become +zero, typically at scope exit: use IO::File; #... sub read_myfile_munged { my $ALL = shift; + # or just leave it undef to autoviv my $handle = IO::File->new; - open($handle, "myfile") or die "myfile: $!"; + open($handle, "<", "myfile") or die "myfile: $!"; $first = <$handle> or return (); # Automatically closed here. - mung $first or die "mung failed"; # Or here. - return $first, <$handle> if $ALL; # Or here. - $first; # Or here. + mung($first) or die "mung failed"; # Or here. + return (first, <$handle>) if $ALL; # Or here. + return $first; # Or here. } +B<WARNING:> The previous example has a bug because the automatic +close that happens when the refcount on C<handle> does not +properly detect and report failures. I<Always> close the handle +yourself and inspect the return value. + + close($handle) + || warn "close failed: $!"; + See L</seek> for some details about mixing reading and writing. =item opendir DIRHANDLE,EXPR @@ -3569,10 +3713,10 @@ C<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful. DIRHANDLE may be an expression whose value can be used as an indirect dirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined scalar variable (or array or hash element), the variable is assigned a -reference to a new anonymous dirhandle. +reference to a new anonymous dirhandle; that is, it's autovivified. DIRHANDLEs have their own namespace separate from FILEHANDLEs. -See example at C<readdir>. +See the example at C<readdir>. =item ord EXPR X<ord> X<encoding> @@ -3580,8 +3724,9 @@ X<ord> X<encoding> =item ord Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC, -or Unicode) value of the first character of EXPR. If EXPR is omitted, -uses C<$_>. +or Unicode) value of the first character of EXPR. +If EXPR is an empty string, returns 0. If EXPR is omitted, uses C<$_>. +(Note I<character>, not byte.) For the reverse, see L</chr>. See L<perlunicode> for more about Unicode. @@ -3599,14 +3744,14 @@ C<our> associates a simple name with a package variable in the current package for use within the current scope. When C<use strict 'vars'> is in effect, C<our> lets you use declared global variables without qualifying them with package names, within the lexical scope of the C<our> declaration. -In this way C<our> differs from C<use vars>, which is package scoped. +In this way C<our> differs from C<use vars>, which is package-scoped. -Unlike C<my>, which both allocates storage for a variable and associates -a simple name with that storage for use within the current scope, C<our> -associates a simple name with a package variable in the current package, -for use within the current scope. In other words, C<our> has the same -scoping rules as C<my>, but does not necessarily create a -variable. +Unlike C<my> or C<state>, which allocates storage for a variable and +associates a simple name with that storage for use within the current +scope, C<our> associates a simple name with a package (read: global) +variable in the current package, for use within the current lexical scope. +In other words, C<our> has the same scoping rules as C<my> or C<state>, but +does not necessarily create a variable. If more than one value is listed, the list must be placed in parentheses. @@ -3826,7 +3971,7 @@ packed string. =item * And if it's an integer I<n>, the offset is relative to the start of the -I<n>th innermost C<()> group, or to the start of the string if I<n> is +I<n>th innermost C<( )> group, or to the start of the string if I<n> is bigger then the group level. =back @@ -3840,17 +3985,18 @@ count should not be more than 65. The C<a>, C<A>, and C<Z> types gobble just one value, but pack it as a string of length count, padding with nulls or spaces as needed. When unpacking, C<A> strips trailing whitespace and nulls, C<Z> strips everything -after the first null, and C<a> returns data without any sort of trimming. +after the first null, and C<a> returns data with no stripping at all. If the value to pack is too long, the result is truncated. If it's too long and an explicit count is provided, C<Z> packs only C<$count-1> bytes, followed by a null byte. Thus C<Z> always packs a trailing null, except -for when the count is 0. +when the count is 0. =item * Likewise, the C<b> and C<B> formats pack a string that's that many bits long. -Each such format generates 1 bit of the result. +Each such format generates 1 bit of the result. These are typically followed +by a repeat count like C<B8> or C<B64>. Each result bit is based on the least-significant bit of the corresponding input character, i.e., on C<ord($char)%2>. In particular, characters C<"0"> @@ -3869,21 +4015,21 @@ at the end. Similarly during unpacking, "extra" bits are ignored. If the input string is longer than needed, remaining characters are ignored. A C<*> for the repeat count uses all characters of the input field. -On unpacking, bits are converted to a string of C<"0">s and C<"1">s. +On unpacking, bits are converted to a string of C<0>s and C<1>s. =item * The C<h> and C<H> formats pack a string that many nybbles (4-bit groups, representable as hexadecimal digits, C<"0".."9"> C<"a".."f">) long. -For each such format, pack() generates 4 bits of the result. +For each such format, pack() generates 4 bits of result. With non-alphabetical characters, the result is based on the 4 least-significant bits of the input character, i.e., on C<ord($char)%16>. In particular, characters C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes -C<"\0"> and C<"\1">. For characters C<"a".."f"> and C<"A".."F">, the result +C<"\000"> and C<"\001">. For characters C<"a".."f"> and C<"A".."F">, the result is compatible with the usual hexadecimal digits, so that C<"a"> and -C<"A"> both generate the nybble C<0xa==10>. Do not use any characters -but these with this format. +C<"A"> both generate the nybble C<0xA==10>. Use only these specific hex +characters with this format. Starting from the beginning of the template to pack(), each pair of characters is converted to 1 character of output. With format C<h>, the @@ -3943,7 +4089,7 @@ the I<length-item> is the string length, not the number of strings. With an explicit repeat count for pack, the packed string is adjusted to that length. For example: - unpack("W/a", "\04Gurusamy") gives ("Guru") + unpack("W/a", "\004Gurusamy") gives ("Guru") unpack("a3/A A*", "007 Bond J ") gives (" Bond", "J") unpack("a3 x2 /A A*", "007: Bond, J.") gives ("Bond, J", ".") @@ -4010,8 +4156,8 @@ handled by the CPU registers) into bytes as Basically, Intel and VAX CPUs are little-endian, while everybody else, including Motorola m68k/88k, PPC, Sparc, HP PA, Power, and Cray, are -big-endian. Alpha and MIPS can be either: Digital/Compaq used/uses them in -little-endian mode, but SGI/Cray uses them in big-endian mode. +big-endian. Alpha and MIPS can be either: Digital/Compaq uses (well, used) +them in little-endian mode, but SGI/Cray uses them in big-endian mode. The names I<big-endian> and I<little-endian> are comic references to the egg-eating habits of the little-endian Lilliputians and the big-endian @@ -4051,10 +4197,10 @@ Starting with Perl 5.9.2, integer and floating-point formats, along with the C<p> and C<P> formats and C<()> groups, may all be followed by the C<< > >> or C<< < >> endianness modifiers to respectively enforce big- or little-endian byte-order. These modifiers are especially useful -given how C<n>, C<N>, C<v> and C<V> don't cover signed integers, +given how C<n>, C<N>, C<v>, and C<V> don't cover signed integers, 64-bit integers, or floating-point values. -Here are some concerns to keep in mind when using endianness modifier: +Here are some concerns to keep in mind when using an endianness modifier: =over @@ -4118,6 +4264,26 @@ starts with C<U>. You can always switch mode mid-format with an explicit C<C0> or C<U0> in the format. This mode remains in effect until the next mode change, or until the end of the C<()> group it (directly) applies to. +Using C<C0> to get Unicode characters while using C<U0> to get I<non>-Unicode +bytes is not necessarily obvious. Probably only the first of these +is what you want: + + $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | + perl -CS -ne 'printf "%v04X\n", $_ for unpack("C0A*", $_)' + 03B1.03C9 + $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | + perl -CS -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)' + CE.B1.CF.89 + $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | + perl -C0 -ne 'printf "%v02X\n", $_ for unpack("C0A*", $_)' + CE.B1.CF.89 + $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | + perl -C0 -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)' + C3.8E.C2.B1.C3.8F.C2.89 + +Those examples also illustrate that you should not try to use +C<pack>/C<unpack> as a substitute for the L<Encode> module. + =item * You must yourself do any alignment or padding by inserting, for example, @@ -4173,7 +4339,7 @@ for complicated pattern matches. =item * -If TEMPLATE requires more arguments that pack() is given, pack() +If TEMPLATE requires more arguments than pack() is given, pack() assumes additional C<""> arguments. If TEMPLATE requires fewer arguments than given, extra arguments are ignored. @@ -4204,8 +4370,8 @@ Examples: # $foo = pack("WWWW",193,194,195,196); $foo = pack("s2",1,2); - # "\1\0\2\0" on little-endian - # "\0\1\0\2" on big-endian + # "\001\000\002\000" on little-endian + # "\000\001\000\002" on big-endian $foo = pack("a4","abcd","x","y","z"); # "abcd" @@ -4249,18 +4415,30 @@ Examples: The same template may generally also be used in unpack(). +=item package NAMESPACE + =item package NAMESPACE VERSION X<package> X<module> X<namespace> X<version> -=item package NAMESPACE +=item package NAMESPACE BLOCK + +=item package NAMESPACE VERSION BLOCK +X<package> X<module> X<namespace> X<version> + +Declares the BLOCK or the rest of the compilation unit as being in the +given namespace. The scope of the package declaration is either the +supplied code BLOCK or, in the absence of a BLOCK, from the declaration +itself through the end of current scope (the enclosing block, file, or +C<eval>). That is, the forms without a BLOCK are operative through the end +of the current scope, just like the C<my>, C<state>, and C<our> operators. +All unqualified dynamic identifiers in this scope will be in the given +namespace, except where overridden by another C<package> declaration or +when they're one of the special identifiers that qualify into C<main::>, +like C<STDOUT>, C<ARGV>, C<ENV>, and the punctuation variables. -Declares the compilation unit as being in the given namespace. The scope -of the package declaration is from the declaration itself through the end -of the enclosing block, file, or eval (the same as the C<my> operator). -All further unqualified dynamic identifiers will be in this namespace. A package statement affects dynamic variables only, including those you've used C<local> on, but I<not> lexical variables, which are created -with C<my> (or C<our> (or C<state>)). Typically it would be the first +with C<my>, C<state>, or C<our>. Typically it would be the first declaration in a file included by C<require> or C<use>. You can switch into a package in more than one place, since this only determines which default symbol table the compiler uses for the rest of that block. You can refer to @@ -4290,7 +4468,8 @@ unless you are very careful. In addition, note that Perl's pipes use IO buffering, so you may need to set C<$|> to flush your WRITEHANDLE after each command, depending on the application. -See L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication"> +See L<IPC::Open2>, L<IPC::Open3>, and +L<perlipc/"Bidirectional Communication with Another Process"> for examples of such things. On systems that support a close-on-exec flag on files, that flag is set @@ -4300,6 +4479,8 @@ the current value of $^F (by default 2 for C<STDERR>). See L<perlvar/$^F>. =item pop ARRAY X<pop> X<stack> +=item pop EXPR + =item pop Pops and returns the last value of the array, shortening the array by @@ -4309,53 +4490,71 @@ Returns the undefined value if the array is empty, although this may also happen at other times. If ARRAY is omitted, pops the C<@ARGV> array in the main program, but the C<@_> array in subroutines, just like C<shift>. +Starting with Perl 5.14, C<pop> can take a scalar EXPR, which must hold a +reference to an unblessed array. The argument will be dereferenced +automatically. This aspect of C<pop> is considered highly experimental. +The exact behaviour may change in a future version of Perl. + =item pos SCALAR X<pos> X<match, position> =item pos -Returns the offset of where the last C<m//g> search left off for the variable -in question (C<$_> is used when the variable is not specified). Note that -0 is a valid match offset. C<undef> indicates that the search position -is reset (usually due to match failure, but can also be because no match has -yet been run on the scalar). C<pos> directly accesses the location used -by the regexp engine to store the offset, so assigning to C<pos> will change -that offset, and so will also influence the C<\G> zero-width assertion in -regular expressions. Because a failed C<m//gc> match doesn't reset the offset, -the return from C<pos> won't change either in this case. See L<perlre> and +Returns the offset of where the last C<m//g> search left off for the +variable in question (C<$_> is used when the variable is not +specified). Note that 0 is a valid match offset. C<undef> indicates +that the search position is reset (usually due to match failure, but +can also be because no match has yet been run on the scalar). + +C<pos> directly accesses the location used by the regexp engine to +store the offset, so assigning to C<pos> will change that offset, and +so will also influence the C<\G> zero-width assertion in regular +expressions. Both of these effects take place for the next match, so +you can't affect the position with C<pos> during the current match, +such as in C<(?{pos() = 5})> or C<s//pos() = 5/e>. + +Setting C<pos> also resets the I<matched with zero-length> flag, described +under L<perlre/"Repeated Patterns Matching a Zero-length Substring">. + +Because a failed C<m//gc> match doesn't reset the offset, the return +from C<pos> won't change either in this case. See L<perlre> and L<perlop>. =item print FILEHANDLE LIST X<print> +=item print FILEHANDLE + =item print LIST =item print Prints a string or a list of strings. Returns true if successful. -FILEHANDLE may be a scalar variable containing -the name of or a reference to the filehandle, thus introducing -one level of indirection. (NOTE: If FILEHANDLE is a variable and -the next token is a term, it may be misinterpreted as an operator -unless you interpose a C<+> or put parentheses around the arguments.) -If FILEHANDLE is omitted, prints to standard output by default, or -to the last selected output channel; see L</select>. If LIST is -also omitted, prints C<$_> to the currently selected output handle. -To set the default output handle to something other than STDOUT -use the select operation. The current value of C<$,> (if any) is -printed between each LIST item. The current value of C<$\> (if -any) is printed after the entire LIST has been printed. Because -print takes a LIST, anything in the LIST is evaluated in list -context, and any subroutine that you call will have one or more of -its expressions evaluated in list context. Also be careful not to -follow the print keyword with a left parenthesis unless you want -the corresponding right parenthesis to terminate the arguments to -the print; put parentheses around all the arguments +FILEHANDLE may be a scalar variable containing the name of or a reference +to the filehandle, thus introducing one level of indirection. (NOTE: If +FILEHANDLE is a variable and the next token is a term, it may be +misinterpreted as an operator unless you interpose a C<+> or put +parentheses around the arguments.) If FILEHANDLE is omitted, prints to the +last selected (see L</select>) output handle. If LIST is omitted, prints +C<$_> to the currently selected output handle. To use FILEHANDLE alone to +print the content of C<$_> to it, you must use a real filehandle like +C<FH>, not an indirect one like C<$fh>. To set the default output handle +to something other than STDOUT, use the select operation. + +The current value of C<$,> (if any) is printed between each LIST item. The +current value of C<$\> (if any) is printed after the entire LIST has been +printed. Because print takes a LIST, anything in the LIST is evaluated in +list context, including any subroutines whose return lists you pass to +C<print>. Be careful not to follow the print keyword with a left +parenthesis unless you want the corresponding right parenthesis to +terminate the arguments to the print; put parentheses around all arguments (or interpose a C<+>, but that doesn't look as good). -Note that if you're storing FILEHANDLEs in an array, or if you're using -any other expression more complex than a scalar variable to retrieve it, -you will have to use a block returning the filehandle value instead: +If you're storing handles in an array or hash, or in general whenever +you're using any expression more complex than a bareword handle or a plain, +unsubscripted scalar variable to retrieve it, you will have to use a block +returning the filehandle value instead, in which case the LIST may not be +omitted: print { $files[$i] } "stuff\n"; print { $OK ? STDOUT : STDERR } "stuff\n"; @@ -4366,15 +4565,21 @@ L<perlipc> for more on signal handling. =item printf FILEHANDLE FORMAT, LIST X<printf> +=item printf FILEHANDLE + =item printf FORMAT, LIST +=item printf + Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\> -(the output record separator) is not appended. The first argument -of the list will be interpreted as the C<printf> format. See C<sprintf> -for an explanation of the format argument. If C<use locale> is in effect, -and POSIX::setlocale() has been called, the character used for the decimal +(the output record separator) is not appended. The first argument of the +list will be interpreted as the C<printf> format. See C<sprintf> for an +explanation of the format argument. If you omit the LIST, C<$_> is used; +to use FILEHANDLE without a LIST, you must use a real filehandle like +C<FH>, not an indirect one like C<$fh>. If C<use locale> is in effect and +POSIX::setlocale() has been called, the character used for the decimal separator in formatted floating-point numbers is affected by the LC_NUMERIC -locale. See L<perllocale> and L<POSIX>. +locale setting. See L<perllocale> and L<POSIX>. Don't fall into the trap of using a C<printf> when a simple C<print> would do. The C<print> is more efficient and less @@ -4397,9 +4602,11 @@ describing the equivalent prototype is returned. =item push ARRAY,LIST X<push> X<stack> -Treats ARRAY as a stack, and pushes the values of LIST -onto the end of ARRAY. The length of ARRAY increases by the length of -LIST. Has the same effect as +=item push EXPR,LIST + +Treats ARRAY as a stack by appending the values of LIST to the end of +ARRAY. The length of ARRAY increases by the length of LIST. Has the same +effect as for $value (LIST) { $ARRAY[++$#ARRAY] = $value; @@ -4408,6 +4615,11 @@ LIST. Has the same effect as but is more efficient. Returns the number of elements in the array following the completed C<push>. +Starting with Perl 5.14, C<push> can take a scalar EXPR, which must hold a +reference to an unblessed array. The argument will be dereferenced +automatically. This aspect of C<push> is considered highly experimental. +The exact behaviour may change in a future version of Perl. + =item q/STRING/ =item qq/STRING/ @@ -4459,8 +4671,13 @@ Or: my $quoted_substring = quotemeta($substring); $sentence =~ s{$quoted_substring}{big bad wolf}; -Will both leave the sentence as is. Normally, when accepting string input from -the user, quotemeta() or C<\Q> must be used. +Will both leave the sentence as is. Normally, when accepting literal string +input from the user, quotemeta() or C<\Q> must be used. + +In Perl 5.14, all characters whose code points are above 127 are not +quoted in UTF8-encoded strings, but all are quoted in UTF-8 strings. +It is planned to change this behavior in 5.16, but the exact rules +haven't been determined yet. =item rand EXPR X<rand> X<random> @@ -4485,6 +4702,13 @@ returns a random integer between C<0> and C<9>, inclusive. large or too small, then your version of Perl was probably compiled with the wrong number of RANDBITS.) +B<C<rand()> is not cryptographically secure. You should not rely +on it in security-sensitive situations.> As of this writing, a +number of third-party CPAN modules offer random number generators +intended by their authors to be cryptographically secure, +including: L<Math::Random::Secure>, L<Math::Random::MT::Perl>, and +L<Math::TrulyRandom>. + =item read FILEHANDLE,SCALAR,LENGTH,OFFSET X<read> X<file, read> @@ -4508,10 +4732,10 @@ The call is implemented in terms of either Perl's or your system's native fread(3) library function. To get a true read(2) system call, see C<sysread>. Note the I<characters>: depending on the status of the filehandle, -either (8-bit) bytes or characters are read. By default all +either (8-bit) bytes or characters are read. By default, all filehandles operate on bytes, but for example if the filehandle has been opened with the C<:utf8> I/O layer (see L</open>, and the C<open> -pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode +pragma, L<open>), the I/O will operate on UTF8-encoded Unicode characters, not bytes. Similarly for the C<:encoding> pragma: in that case pretty much any characters can be read. @@ -4546,7 +4770,7 @@ which will set C<$_> on every iteration. X<readline> X<gets> X<fgets> Reads from the filehandle whose typeglob is contained in EXPR (or from -*ARGV if EXPR is not provided). In scalar context, each call reads and +C<*ARGV> if EXPR is not provided). In scalar context, each call reads and returns the next line until end-of-file is reached, whereupon the subsequent call returns C<undef>. In list context, reads until end-of-file is reached and returns a list of lines. Note that the notion of "line" @@ -4630,7 +4854,7 @@ Note the I<characters>: depending on the status of the socket, either (8-bit) bytes or characters are received. By default all sockets operate on bytes, but for example if the socket has been changed using binmode() to operate with the C<:encoding(utf8)> I/O layer (see the -C<open> pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode +C<open> pragma, L<open>), the I/O will operate on UTF8-encoded Unicode characters, not bytes. Similarly for the C<:encoding> pragma: in that case pretty much any characters can be read. @@ -4663,7 +4887,7 @@ normally use this command: } C<redo> cannot be used to retry a block that returns a value such as -C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit +C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit a grep() or map() operation. Note that a block by itself is semantically identical to a loop @@ -4832,9 +5056,9 @@ first look for a similar filename with a "F<.pmc>" extension. If this file is found, it will be loaded in place of any file ending in a "F<.pm>" extension. -You can also insert hooks into the import facility, by putting Perl code +You can also insert hooks into the import facility by putting Perl code directly into the @INC array. There are three forms of hooks: subroutine -references, array references and blessed objects. +references, array references, and blessed objects. Subroutine references are the simplest case. When the inclusion system walks through @INC and encounters a subroutine, this subroutine gets @@ -4853,8 +5077,8 @@ A filehandle, from which the file will be read. A reference to a subroutine. If there is no filehandle (previous item), then this subroutine is expected to generate one line of source code per -call, writing the line into C<$_> and returning 1, then returning 0 at -end of file. If there is a filehandle, then the subroutine will be +call, writing the line into C<$_> and returning 1, then finally at end of +file returning 0. If there is a filehandle, then the subroutine will be called to act as a simple source filter, with the line as read in C<$_>. Again, return 1 for each valid line, and 0 after all lines have been returned. @@ -4869,8 +5093,8 @@ reference to the subroutine itself is passed in as C<$_[0]>. If an empty list, C<undef>, or nothing that matches the first 3 values above is returned, then C<require> looks at the remaining elements of @INC. Note that this filehandle must be a real filehandle (strictly a typeglob -or reference to a typeglob, blessed or unblessed); tied filehandles will be -ignored and return value processing will stop there. +or reference to a typeglob, whether blessed or unblessed); tied filehandles +will be ignored and processing will stop there. If the hook is an array reference, its first element must be a subroutine reference. This subroutine is called as above, but the first parameter is @@ -5007,7 +5231,7 @@ X<rmdir> X<rd> X<directory, remove> =item rmdir Deletes the directory specified by FILENAME if that directory is -empty. If it succeeds it returns true, otherwise it returns false and +empty. If it succeeds it returns true; otherwise it returns false and sets C<$!> (errno). If FILENAME is omitted, uses C<$_>. To remove a directory tree recursively (C<rm -rf> on Unix) look at @@ -5020,16 +5244,20 @@ The substitution operator. See L<perlop/"Regexp Quote-Like Operators">. =item say FILEHANDLE LIST X<say> +=item say FILEHANDLE + =item say LIST =item say -Just like C<print>, but implicitly appends a newline. -C<say LIST> is simply an abbreviation for C<{ local $\ = "\n"; print -LIST }>. +Just like C<print>, but implicitly appends a newline. C<say LIST> is +simply an abbreviation for C<{ local $\ = "\n"; print LIST }>. To use +FILEHANDLE without a LIST to print the contents of C<$_> to it, you must +use a real filehandle like C<FH>, not an indirect one like C<$fh>. -This keyword is available only when the "say" feature is -enabled: see L<feature>. +This keyword is available only when the C<"say"> feature is enabled; see +L<feature>. Alternately, include a C<use v5.10> or later to the current +scope. =item scalar EXPR X<scalar> X<context> @@ -5045,10 +5273,10 @@ needed. If you really wanted to do so, however, you could use the construction C<@{[ (some expression) ]}>, but usually a simple C<(some expression)> suffices. -Because C<scalar> is a unary operator, if you accidentally use for EXPR a -parenthesized list, this behaves as a scalar comma expression, evaluating -all but the last element in void context and returning the final element -evaluated in scalar context. This is seldom what you want. +Because C<scalar> is a unary operator, if you accidentally use a +parenthesized list for the EXPR, this behaves as a scalar comma expression, +evaluating all but the last element in void context and returning the final +element evaluated in scalar context. This is seldom what you want. The following single statement: @@ -5067,11 +5295,11 @@ X<seek> X<fseek> X<filehandle, position> Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>. FILEHANDLE may be an expression whose value gives the name of the filehandle. The values for WHENCE are C<0> to set the new position -I<in bytes> to POSITION, C<1> to set it to the current position plus -POSITION, and C<2> to set it to EOF plus POSITION (typically -negative). For WHENCE you may use the constants C<SEEK_SET>, +I<in bytes> to POSITION; C<1> to set it to the current position plus +POSITION; and C<2> to set it to EOF plus POSITION, typically +negative. For WHENCE you may use the constants C<SEEK_SET>, C<SEEK_CUR>, and C<SEEK_END> (start of the file, current position, end -of the file) from the Fcntl module. Returns C<1> on success, C<0> +of the file) from the L<Fcntl> module. Returns C<1> on success, false otherwise. Note the I<in bytes>: even if the filehandle has been set to @@ -5123,11 +5351,12 @@ X<select> X<filehandle, default> Returns the currently selected filehandle. If FILEHANDLE is supplied, sets the new current default filehandle for output. This has two -effects: first, a C<write> or a C<print> without a filehandle will +effects: first, a C<write> or a C<print> without a filehandle default to this FILEHANDLE. Second, references to variables related to -output will refer to this output channel. For example, if you have to -set the top of form format for more than one output channel, you might -do the following: +output will refer to this output channel. + +For example, to set the top-of-form format for more than one +output channel, you might do the following: select(REPORT1); $^ = 'report1_top'; @@ -5197,11 +5426,10 @@ portability of C<select>. On error, C<select> behaves like select(2): it returns -1 and sets C<$!>. -On some Unixes, select(2) may report a socket file -descriptor as "ready for reading" when no data is available, and -thus a subsequent read blocks. This can be avoided if you always use -O_NONBLOCK on the socket. See select(2) and fcntl(2) for further -details. +On some Unixes, select(2) may report a socket file descriptor as "ready for +reading" even when no data is available, and thus any subsequent C<read> +would block. This can be avoided if you always use O_NONBLOCK on the +socket. See select(2) and fcntl(2) for further details. B<WARNING>: One should not attempt to mix buffered I/O (like C<read> or <FH>) with C<select>, except as permitted by POSIX, and even @@ -5227,7 +5455,7 @@ documentation. X<semget> Calls the System V IPC function semget(2). Returns the semaphore id, or -the undefined value if there is an error. See also +the undefined value on error. See also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore> documentation. @@ -5239,7 +5467,7 @@ such as signalling and waiting. OPSTRING must be a packed array of semop structures. Each semop structure can be generated with C<pack("s!3", $semnum, $semop, $semflag)>. The length of OPSTRING implies the number of semaphore operations. Returns true if -successful, or false if there is an error. As an example, the +successful, false on error. As an example, the following code waits on semaphore $semnum of semaphore id $semid: $semop = pack("s!3", $semnum, -1, 0); @@ -5289,8 +5517,8 @@ that doesn't implement setpriority(2). =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL X<setsockopt> -Sets the socket option requested. Returns undefined if there is an -error. Use integer constants provided by the C<Socket> module for +Sets the socket option requested. Returns C<undef> on error. +Use integer constants provided by the C<Socket> module for LEVEL and OPNAME. Values for LEVEL can also be obtained from getprotobyname. OPTVAL might either be a packed string or an integer. An integer OPTVAL is shorthand for pack("i", OPTVAL). @@ -5303,6 +5531,8 @@ An example disabling Nagle's algorithm on a socket: =item shift ARRAY X<shift> +=item shift EXPR + =item shift Shifts the first value of the array off and returns it, shortening the @@ -5311,7 +5541,12 @@ array, returns the undefined value. If ARRAY is omitted, shifts the C<@_> array within the lexical scope of subroutines and formats, and the C<@ARGV> array outside a subroutine and also within the lexical scopes established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>, -C<UNITCHECK {}> and C<END {}> constructs. +C<UNITCHECK {}>, and C<END {}> constructs. + +Starting with Perl 5.14, C<shift> can take a scalar EXPR, which must hold a +reference to an unblessed array. The argument will be dereferenced +automatically. This aspect of C<shift> is considered highly experimental. +The exact behaviour may change in a future version of Perl. See also C<unshift>, C<push>, and C<pop>. C<shift> and C<unshift> do the same thing to the left end of an array that C<pop> and C<push> do to the @@ -5326,15 +5561,15 @@ Calls the System V IPC function shmctl. You'll probably have to say first to get the correct constant definitions. If CMD is C<IPC_STAT>, then ARG must be a variable that will hold the returned C<shmid_ds> -structure. Returns like ioctl: the undefined value for error, "C<0> but -true" for zero, or the actual return value otherwise. +structure. Returns like ioctl: C<undef> for error; "C<0> but +true" for zero; and the actual return value otherwise. See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation. =item shmget KEY,SIZE,FLAGS X<shmget> Calls the System V IPC function shmget. Returns the shared memory -segment id, or the undefined value if there is an error. +segment id, or C<undef> on error. See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation. =item shmread ID,VAR,POS,SIZE @@ -5348,9 +5583,9 @@ position POS for size SIZE by attaching to it, copying in/out, and detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out -SIZE bytes. Return true if successful, or false if there is an error. +SIZE bytes. Return true if successful, false on error. shmread() taints the variable. See also L<perlipc/"SysV IPC">, -C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN. +C<IPC::SysV>, and the C<IPC::Shareable> module from CPAN. =item shutdown SOCKET,HOW X<shutdown> @@ -5476,13 +5711,12 @@ the value provides the name of (or a reference to) the actual subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine. -If the subroutine's prototype is C<($$)>, the elements to be compared -are passed by reference in C<@_>, as for a normal subroutine. This is -slower than unprototyped subroutines, where the elements to be -compared are passed into the subroutine -as the package global variables $a and $b (see example below). Note that -in the latter case, it is usually counter-productive to declare $a and -$b as lexicals. +If the subroutine's prototype is C<($$)>, the elements to be compared are +passed by reference in C<@_>, as for a normal subroutine. This is slower +than unprototyped subroutines, where the elements to be compared are passed +into the subroutine as the package global variables $a and $b (see example +below). Note that in the latter case, it is usually highly counter-productive +to declare $a and $b as lexicals. The values to be compared are always passed by reference and should not be modified. @@ -5500,7 +5734,7 @@ actually modifies the element in the original list. This is usually something to be avoided when writing clear code. Perl 5.6 and earlier used a quicksort algorithm to implement sort. -That algorithm was not stable, and I<could> go quadratic. (A I<stable> sort +That algorithm was not stable, so I<could> go quadratic. (A I<stable> sort preserves the input order of elements that compare equal. Although quicksort's run time is O(NlogN) when averaged over all arrays of length N, the time can be O(N**2), I<quadratic> behavior, for some @@ -5636,22 +5870,22 @@ sometimes saying the opposite, for example) the results are not well-defined. Because C<< <=> >> returns C<undef> when either operand is C<NaN> -(not-a-number), and because C<sort> raises an exception unless the -result of a comparison is defined, when sorting with a comparison function -like C<< $a <=> $b >>, be careful about lists that might contain a C<NaN>. -The following example takes advantage that C<NaN != NaN> to +(not-a-number), and laso because C<sort> raises an exception unless the +result of a comparison is defined, be careful when sorting with a +comparison function like C<< $a <=> $b >> any lists that might contain a +C<NaN>. The following example takes advantage that C<NaN != NaN> to eliminate any C<NaN>s from the input list. @result = sort { $a <=> $b } grep { $_ == $_ } @input; -=item splice ARRAY,OFFSET,LENGTH,LIST +=item splice ARRAY or EXPR,OFFSET,LENGTH,LIST X<splice> -=item splice ARRAY,OFFSET,LENGTH +=item splice ARRAY or EXPR,OFFSET,LENGTH -=item splice ARRAY,OFFSET +=item splice ARRAY or EXPR,OFFSET -=item splice ARRAY +=item splice ARRAY or EXPR Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. In list context, @@ -5687,6 +5921,11 @@ Example, assuming array lengths are passed before arrays: } if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... } +Starting with Perl 5.14, C<splice> can take scalar EXPR, which must hold a +reference to an unblessed array. The argument will be dereferenced +automatically. This aspect of C<splice> is considered highly experimental. +The exact behaviour may change in a future version of Perl. + =item split /PATTERN/,EXPR,LIMIT X<split> @@ -5957,11 +6196,11 @@ display the given value. You can override the width by putting a number here, or get the width from the next argument (with C<*>) or from a specified argument (e.g., with C<*2$>): - printf '<%s>', "a"; # prints "<a>" - printf '<%6s>', "a"; # prints "< a>" - printf '<%*s>', 6, "a"; # prints "< a>" - printf '<%*2$s>', "a", 6; # prints "< a>" - printf '<%2s>', "long"; # prints "<long>" (does not truncate) + printf "<%s>", "a"; # prints "<a>" + printf "<%6s>", "a"; # prints "< a>" + printf "<%*s>", 6, "a"; # prints "< a>" + printf "<%*2$s>", "a", 6; # prints "< a>" + printf "<%2s>", "long"; # prints "<long>" (does not truncate) If a field width obtained through C<*> is negative, it has the same effect as the C<-> flag: left-justification. @@ -5971,7 +6210,7 @@ X<precision> You can specify a precision (for numeric conversions) or a maximum width (for string conversions) by specifying a C<.> followed by a number. -For floating-point formats except 'g' and 'G', this specifies +For floating-point formats except C<g> and C<G>, this specifies how many places right of the decimal point to show (the default being 6). For example: @@ -6051,15 +6290,30 @@ whatever the default integer size is on your platform (usually 32 or 64 bits), but you can override this to use instead one of the standard C types, as supported by the compiler used to build Perl: - l interpret integer as C type "long" or "unsigned long" + hh interpret integer as C type "char" or "unsigned char" + on Perl 5.14 or later h interpret integer as C type "short" or "unsigned short" - q, L or ll interpret integer as C type "long long", "unsigned long long". - or "quads" (typically 64-bit integers) + j intepret integer as C type "intmax_t" on Perl 5.14 + or later, and only with a C99 compiler (unportable) + l interpret integer as C type "long" or "unsigned long" + q, L, or ll interpret integer as C type "long long", "unsigned long long", + or "quad" (typically 64-bit integers) + t intepret integer as C type "ptrdiff_t" on Perl 5.14 or later + z intepret integer as C type "size_t" on Perl 5.14 or later -The last will raise an exception if Perl does not understand "quads" in your -installation. (This requires either that the platform natively support quads, -or that Perl were specifically compiled to support quads.) You can find out -whether your Perl supports quads via L<Config>: +As of 5.14, none of these raises an exception if they are not supported on +your platform. However, if warnings are enabled, a warning of the +C<printf> warning class is issued on an unsupported conversion flag. +Should you instead prefer an exception, do this: + + use warnings FATAL => "printf"; + +If you would like to know about a version dependency before you +start running the program, put something like this at its top: + + use 5.014; # for hh/j/t/z/ printf modifiers + +You can find out whether your Perl supports quads via L<Config>: use Config; if ($Config{use64bitint} eq "define" || $Config{longsize} >= 8) { @@ -6148,34 +6402,34 @@ X<srand> X<seed> X<randseed> =item srand -Sets the random number seed for the C<rand> operator. +Sets and returns the random number seed for the C<rand> operator. The point of the function is to "seed" the C<rand> function so that C<rand> can produce a different sequence each time you run your -program. - -If srand() is not called explicitly, it is called implicitly at the -first use of the C<rand> operator. However, this was not true of -versions of Perl before 5.004, so if your script will run under older -Perl versions, it should call C<srand>. - -Most programs won't even call srand() at all, except those that -need a cryptographically-strong starting point rather than the -generally acceptable default, which is based on time of day, -process ID, and memory allocation, or the F</dev/urandom> device -if available. You may also want to call srand() after a fork() to -avoid child processes sharing the same seed value as the parent (and -consequently each other). - -You can call srand($seed) with the same $seed to reproduce the -I<same> sequence from rand(), but this is usually reserved for -generating predictable results for testing or debugging. -Otherwise, don't call srand() more than once in your program. - -Do B<not> call srand() (i.e., without an argument) more than once per +program. When called with a parameter, C<srand> uses that for the seed; +otherwise it (semi-)randomly chooses a seed. In either case, starting with +Perl 5.14, it returns the seed. + +If C<srand()> is not called explicitly, it is called implicitly without a +parameter at the first use of the C<rand> operator. However, this was not true +of versions of Perl before 5.004, so if your script will run under older +Perl versions, it should call C<srand>; otherwise most programs won't call +C<srand()> at all. + +But there are a few situations in recent Perls where programs are likely to +want to call C<srand>. One is for generating predictable results generally for +testing or debugging. There, you use C<srand($seed)>, with the same C<$seed> +each time. Another other case is where you need a cryptographically-strong +starting point rather than the generally acceptable default, which is based on +time of day, process ID, and memory allocation, or the F</dev/urandom> device +if available. And still another case is that you may want to call C<srand()> +after a C<fork()> to avoid child processes sharing the same seed value as the +parent (and consequently each other). + +Do B<not> call C<srand()> (i.e., without an argument) more than once per process. The internal state of the random number generator should contain more entropy than can be provided by any seed, so calling -srand() again actually I<loses> randomness. +C<srand()> again actually I<loses> randomness. Most implementations of C<srand> take an integer and will silently truncate decimal numbers. This means C<srand(42)> will usually @@ -6207,6 +6461,11 @@ for a seed can fall prey to the mathematical property that one-third of the time. So don't do that. +A typical use of the returned seed is for a test program which has too many +combinations to test comprehensively in the time available to it each run. It +can test a random subset each time, and should there be a failure, log the seed +used for that run so that it can later be used to reproduce the same results. + =item stat FILEHANDLE X<stat> X<file, status> X<ctime> @@ -6218,7 +6477,7 @@ X<stat> X<file, status> X<ctime> Returns a 13-element list giving the status info for a file, either the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is -omitted, it stats C<$_>. Returns the empty list if C<stat> fails. Typically +omitted, it stats C<$_> (not C<_>!). Returns the empty list if C<stat> fails. Typically used as follows: ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, @@ -6246,7 +6505,7 @@ meanings of the fields: (*) Not all fields are supported on all filesystem types. Notably, the ctime field is non-portable. In particular, you cannot expect it to be a -"creation time", see L<perlport/"Files and Filesystems"> for details. +"creation time"; see L<perlport/"Files and Filesystems"> for details. If C<stat> is passed the special filehandle consisting of an underline, no stat is done, but the current contents of the stat structure from the @@ -6365,9 +6624,9 @@ X<study> Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of doing many pattern matches on the string before it is next modified. This may or may not save time, depending on the nature and number of -patterns you are searching on, and on the distribution of character +patterns you are searching and the distribution of character frequencies in the string to be searched; you probably want to compare -run times with and without it to see which runs faster. Those loops +run times with and without it to see which is faster. Those loops that scan for many short constant strings (including the constant parts of more complex patterns) will benefit most. You may have only one C<study> active at a time: if you study a different scalar the first @@ -6426,13 +6685,13 @@ X<sub> =item sub NAME (PROTO) : ATTRS BLOCK -This is subroutine definition, not a real function I<per se>. -Without a BLOCK it's just a forward declaration. Without a NAME, -it's an anonymous function declaration, and does actually return -a value: the CODE ref of the closure you just created. +This is subroutine definition, not a real function I<per se>. Without a +BLOCK it's just a forward declaration. Without a NAME, it's an anonymous +function declaration, so does return a value: the CODE ref of the closure +just created. See L<perlsub> and L<perlref> for details about subroutines and -references, and L<attributes> and L<Attribute::Handlers> for more +references; see L<attributes> and L<Attribute::Handlers> for more information about attributes. =item substr EXPR,OFFSET,LENGTH,REPLACEMENT @@ -6443,10 +6702,10 @@ X<substr> X<substring> X<mid> X<left> X<right> =item substr EXPR,OFFSET Extracts a substring out of EXPR and returns it. First character is at -offset C<0>, or whatever you've set C<$[> to (but don't do that). +offset C<0> (or whatever you've set C<$[> to (but B<<don't do that>)). If OFFSET is negative (or more precisely, less than C<$[>), starts -that far from the end of the string. If LENGTH is omitted, returns -everything to the end of the string. If LENGTH is negative, leaves that +that far back from the end of the string. If LENGTH is omitted, returns +everything through the end of the string. If LENGTH is negative, leaves that many characters off the end of the string. my $s = "The black cat climbed the green tree"; @@ -6484,7 +6743,7 @@ just as you can with splice(). my $z = substr $s, 14, 7, "jumped from"; # climbed # $s is now "The black cat jumped from the green tree" -Note that the lvalue returned by the 3-arg version of substr() acts as +Note that the lvalue returned by the three-argument version of substr() acts as a 'magic bullet'; each time it is assigned to, it remembers which part of the original string is being modified; for example: @@ -6535,12 +6794,12 @@ which in practice should (usually) suffice. Syscall returns whatever value returned by the system call it calls. If the system call fails, C<syscall> returns C<-1> and sets C<$!> (errno). -Note that some system calls can legitimately return C<-1>. The proper -way to handle such calls is to assign C<$!=0;> before the call and -check the value of C<$!> if syscall returns C<-1>. +Note that some system calls I<can> legitimately return C<-1>. The proper +way to handle such calls is to assign C<$!=0> before the call, then +check the value of C<$!> if C<syscall> returns C<-1>. There's a problem with C<syscall(&SYS_pipe)>: it returns the file -number of the read end of the pipe it creates. There is no way +number of the read end of the pipe it creates, but there is no way to retrieve the file number of the other end. You can avoid this problem by using C<pipe> instead. @@ -6549,16 +6808,16 @@ X<sysopen> =item sysopen FILEHANDLE,FILENAME,MODE,PERMS -Opens the file whose filename is given by FILENAME, and associates it -with FILEHANDLE. If FILEHANDLE is an expression, its value is used as -the name of the real filehandle wanted. This function calls the -underlying operating system's C<open> function with the parameters -FILENAME, MODE, PERMS. +Opens the file whose filename is given by FILENAME, and associates it with +FILEHANDLE. If FILEHANDLE is an expression, its value is used as the real +filehandle wanted; an undefined scalar will be suitably autovivified. This +function calls the underlying operating system's I<open>(2) function with the +parameters FILENAME, MODE, and PERMS. The possible values and flag bits of the MODE parameter are -system-dependent; they are available via the standard module C<Fcntl>. -See the documentation of your operating system's C<open> to see which -values and flag bits are available. You may combine several flags +system-dependent; they are available via the standard module C<Fcntl>. See +the documentation of your operating system's I<open>(2) syscall to see +which values and flag bits are available. You may combine several flags using the C<|>-operator. Some of the most common values are C<O_RDONLY> for opening the file in @@ -6642,20 +6901,19 @@ See L</binmode>, L</open>, and the C<open> pragma, L<open>. =item sysseek FILEHANDLE,POSITION,WHENCE X<sysseek> X<lseek> -Sets FILEHANDLE's system position in bytes using -lseek(2). FILEHANDLE may be an expression whose value gives the name -of the filehandle. The values for WHENCE are C<0> to set the new -position to POSITION, C<1> to set the it to the current position plus -POSITION, and C<2> to set it to EOF plus POSITION (typically -negative). +Sets FILEHANDLE's system position in bytes using lseek(2). FILEHANDLE may +be an expression whose value gives the name of the filehandle. The values +for WHENCE are C<0> to set the new position to POSITION; C<1> to set the it +to the current position plus POSITION; and C<2> to set it to EOF plus +POSITION, typically negative. Note the I<in bytes>: even if the filehandle has been set to operate on characters (for example by using the C<:encoding(utf8)> I/O layer), tell() will return byte offsets, not character offsets (because implementing that would render sysseek() unacceptably slow). -sysseek() bypasses normal buffered IO, so mixing this with reads (other -than C<sysread>, for example C<< <> >> or read()) C<print>, C<write>, +sysseek() bypasses normal buffered IO, so mixing it with reads other +than C<sysread> (for example C<< <> >> or read()) C<print>, C<write>, C<seek>, C<tell>, or C<eof> may cause confusion. For WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>, @@ -6677,7 +6935,7 @@ X<system> X<shell> =item system PROGRAM LIST Does exactly the same thing as C<exec LIST>, except that a fork is -done first, and the parent process waits for the child process to +done first and the parent process waits for the child process to exit. Note that argument processing varies depending on the number of arguments. If there is more than one argument in LIST, or if LIST is an array with more than one value, starts the program @@ -6699,7 +6957,7 @@ of C<IO::Handle> on any open handles. The return value is the exit status of the program as returned by the C<wait> call. To get the actual exit value, shift right by eight (see below). See also L</exec>. This is I<not> what you want to use to capture -the output from a command, for that you should use merely backticks or +the output from a command; for that you should use merely backticks or C<qx//>, as described in L<perlop/"`STRING`">. Return value of -1 indicates a failure to start the program or an error of the wait(2) system call (inspect $! for the reason). @@ -6755,7 +7013,7 @@ specified FILEHANDLE, using write(2). If LENGTH is not specified, writes whole SCALAR. It bypasses buffered IO, so mixing this with reads (other than C<sysread())>, C<print>, C<write>, C<seek>, C<tell>, or C<eof> may cause confusion because the perlio and -stdio layers usually buffers data. Returns the number of bytes +stdio layers usually buffer data. Returns the number of bytes actually written, or C<undef> if there was an error (in this case the errno variable C<$!> is also set). If the LENGTH is greater than the data available in the SCALAR after the OFFSET, only as much data as is @@ -6766,10 +7024,12 @@ string other than the beginning. A negative OFFSET specifies writing that many characters counting backwards from the end of the string. If SCALAR is of length zero, you can only use an OFFSET of 0. -B<Warning>: If the filehandle is marked C<:utf8>, Unicode characters +B<WARNING>: If the filehandle is marked C<:utf8>, Unicode characters encoded in UTF-8 are written instead of bytes, and the LENGTH, OFFSET, and -return value of syswrite() are in (UTF-8 encoded Unicode) characters. +return value of syswrite() are in (UTF8-encoded Unicode) characters. The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer. +Alternately, if the handle is not marked with an encoding but you +attempt to write characters with code points over 255, raises an exception. See L</binmode>, L</open>, and the C<open> pragma, L<open>. =item tell FILEHANDLE @@ -6794,7 +7054,7 @@ tell() on pipes, fifos, and sockets usually returns -1. There is no C<systell> function. Use C<sysseek(FH, 0, 1)> for that. Do not use tell() (or other buffered I/O operations) on a filehandle -that has been manipulated by sysread(), syswrite() or sysseek(). +that has been manipulated by sysread(), syswrite(), or sysseek(). Those functions ignore the buffering, while tell() does not. =item telldir DIRHANDLE @@ -6914,11 +7174,10 @@ C<localtime>. On most systems the epoch is 00:00:00 UTC, January 1, 1970; a prominent exception being Mac OS Classic which uses 00:00:00, January 1, 1904 in the current local time zone for its epoch. -For measuring time in better granularity than one second, -you may use either the L<Time::HiRes> module (from CPAN, and starting from -Perl 5.8 part of the standard distribution), or if you have -gettimeofday(2), you may be able to use the C<syscall> interface of Perl. -See L<perlfaq8> for details. +For measuring time in better granularity than one second, use the +L<Time::HiRes> module from Perl 5.8 onwards (or from CPAN before then), or, +if you have gettimeofday(2), you may be able to use the C<syscall> +interface of Perl. See L<perlfaq8> for details. For date and time processing look at the many related modules on CPAN. For a comprehensive date and time representation look at the @@ -6927,8 +7186,8 @@ L<DateTime> module. =item times X<times> -Returns a four-element list giving the user and system times, in -seconds, for this process and the children of this process. +Returns a four-element list giving the user and system times in +seconds for this process and any exited children of this process. ($user,$system,$cuser,$csystem) = times; @@ -6948,14 +7207,13 @@ X<truncate> Truncates the file opened on FILEHANDLE, or named by EXPR, to the specified length. Raises an exception if truncate isn't implemented -on your system. Returns true if successful, the undefined value -otherwise. +on your system. Returns true if successful, C<undef> on error. The behavior is undefined if LENGTH is greater than the length of the file. The position in the file of FILEHANDLE is left unchanged. You may want to -call L<seek> before writing to the file. +call L<seek|/"seek FILEHANDLE,POSITION,WHENCE"> before writing to the file. =item uc EXPR X<uc> X<uppercase> X<toupper> @@ -7000,11 +7258,11 @@ and isn't one of the digits). The C<umask> value is such a number representing disabled permissions bits. The permission (or "mode") values you pass C<mkdir> or C<sysopen> are modified by your umask, so even if you tell C<sysopen> to create a file with permissions C<0777>, -if your umask is C<0022> then the file will actually be created with +if your umask is C<0022>, then the file will actually be created with permissions C<0755>. If your C<umask> were C<0027> (group can't write; others can't read, write, or execute), then passing -C<sysopen> C<0666> would create a file with mode C<0640> (C<0666 &~ -027> is C<0640>). +C<sysopen> C<0666> would create a file with mode C<0640> (because +C<0666 &~ 027> is C<0640>). Here's some advice: supply a creation mode of C<0666> for regular files (in C<sysopen>) and one of C<0777> for directories (in @@ -7114,7 +7372,7 @@ a %<number> to indicate that you want a <number>-bit checksum of the items instead of the items themselves. Default is a 16-bit checksum. Checksum is calculated by summing numeric values of expanded values (for string fields the sum of -C<ord($char)> is taken, for bit fields the sum of zeroes and ones). +C<ord($char)> is taken; for bit fields the sum of zeroes and ones). For example, the following computes the same number as the System V sum program: @@ -7151,9 +7409,11 @@ Has no effect if the variable is not tied. =item unshift ARRAY,LIST X<unshift> +=item unshift EXPR,LIST + Does the opposite of a C<shift>. Or the opposite of a C<push>, depending on how you look at it. Prepends list to the front of the -array, and returns the new number of elements in the array. +array and returns the new number of elements in the array. unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/; @@ -7161,6 +7421,11 @@ Note the LIST is prepended whole, not one element at a time, so the prepended elements stay in the same order. Use C<reverse> to do the reverse. +Starting with Perl 5.14, C<unshift> can take a scalar EXPR, which must hold +a reference to an unblessed array. The argument will be dereferenced +automatically. This aspect of C<unshift> is considered highly +experimental. The exact behaviour may change in a future version of Perl. + =item use Module VERSION LIST X<use> X<module> X<import> @@ -7179,6 +7444,7 @@ package. It is exactly equivalent to BEGIN { require Module; Module->import( LIST ); } except that Module I<must> be a bareword. +The importation can be made conditional; see L<if>. In the peculiar C<use VERSION> form, VERSION may be either a positive decimal fraction such as 5.006, which will be compared to C<$]>, or a v-string @@ -7265,7 +7531,7 @@ conditionally, this can be done using the L<if> pragma: use if $] < 5.008, "utf8"; use if WANT_WARNINGS, warnings => qw(all); -There's a corresponding C<no> command that unimports meanings imported +There's a corresponding C<no> declaration that unimports meanings imported by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>. It behaves just as C<import> does with VERSION, an omitted or empty LIST, or no unimport method being found. @@ -7275,7 +7541,7 @@ or no unimport method being found. no warnings; Care should be taken when using the C<no VERSION> form of C<no>. It is -I<only> meant to be used to assert that the running perl is of a earlier +I<only> meant to be used to assert that the running Perl is of a earlier version than its argument and I<not> to undo the feature-enabling side effects of C<use VERSION>. @@ -7287,7 +7553,7 @@ functionality from the command-line. X<utime> Changes the access and modification times on each file of a list of -files. The first two elements of the list must be the NUMERICAL access +files. The first two elements of the list must be the NUMERIC access and modification times, in that order. Returns the number of files successfully changed. The inode change time of each file is set to the current time. For example, this code has the same effect as the @@ -7331,8 +7597,10 @@ X<values> =item values ARRAY +=item values EXPR + Returns a list consisting of all the values of the named hash, or the values -of an array. (In a scalar context, returns the number of values.) +of an array. (In scalar context, returns the number of values.) The values are returned in an apparently random order. The actual random order is subject to change in future versions of Perl, but it @@ -7342,7 +7610,7 @@ function would produce on the same (unmodified) hash. Since Perl for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">). As a side effect, calling values() resets the HASH or ARRAY's internal -iterator, +iterator; see L</each>. (In particular, calling values() in void context resets the iterator with no other overhead. Apart from resetting the iterator, C<values @array> in list context is the same as plain C<@array>. @@ -7350,20 +7618,27 @@ We recommend that you use void context C<keys @array> for this, but reasoned that it taking C<values @array> out would require more documentation than leaving it in.) - Note that the values are not copied, which means modifying them will modify the contents of the hash: for (values %hash) { s/foo/bar/g } # modifies %hash values for (@hash{keys %hash}) { s/foo/bar/g } # same +Starting with Perl 5.14, C<values> can take a scalar EXPR, which must hold +a reference to an unblessed hash or array. The argument will be +dereferenced automatically. This aspect of C<values> is considered highly +experimental. The exact behaviour may change in a future version of Perl. + + for (values $hashref) { ... } + for (values $obj->get_arrayref) { ... } + See also C<keys>, C<each>, and C<sort>. =item vec EXPR,OFFSET,BITS X<vec> X<bit> X<bit vector> Treats the string in EXPR as a bit vector made up of elements of -width BITS, and returns the value of the element specified by OFFSET +width BITS and returns the value of the element specified by OFFSET as an unsigned integer. BITS therefore specifies the number of bits that are reserved for each element in the bit vector. This must be a power of two from 1 to 32 (or 64, if your platform supports @@ -7607,7 +7882,7 @@ 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>. -If you use wait in your handler for $SIG{CHLD} it may accidently wait for the +If you use wait in your handler for $SIG{CHLD} it may accidentally for the child created by qx() or system(). See L<perlipc> for details. =item waitpid PID,FLAGS @@ -7694,10 +7969,57 @@ warnings (even the so-called mandatory ones). An example: # run-time warnings enabled after here warn "\$foo is alive and $foo!"; # does show up -See L<perlvar> for details on setting C<%SIG> entries, and for more +See L<perlvar> for details on setting C<%SIG> entries and for more examples. See the Carp module for other kinds of warnings using its carp() and cluck() functions. +=item when EXPR BLOCK +X<when> + +=item when BLOCK + +C<when> is analogous to the C<case> keyword in other languages. Used with a +C<foreach> loop or the experimental C<given> block, C<when> can be used in +Perl to implement C<switch>/C<case> like statements. Available as a +statement after Perl 5.10 and as a statement modifier after 5.14. +Here are three examples: + + use v5.10; + foreach (@fruits) { + when (/apples?/) { + say "I like apples." + } + when (/oranges?/) { + say "I don't like oranges." + } + default { + say "I don't like anything" + } + } + + # require 5.14 for when as statement modifier + use v5.14; + foreach (@fruits) { + say "I like apples." when /apples?/; + say "I don't like oranges." when /oranges?; + default { say "I don't like anything" } + } + + use v5.10; + given ($fruit) { + when (/apples?/) { + say "I like apples." + } + when (/oranges?/) { + say "I don't like oranges." + } + default { + say "I don't like anything" + } + } + +See L<perlsyn/"Switch statements"> for detailed information. + =item write FILEHANDLE X<write> @@ -7711,15 +8033,15 @@ a file is the one having the same name as the filehandle, but the format for the current output channel (see the C<select> function) may be set explicitly by assigning the name of the format to the C<$~> variable. -Top of form processing is handled automatically: if there is -insufficient room on the current page for the formatted record, the -page is advanced by writing a form feed, a special top-of-page format -is used to format the new page header, and then the record is written. -By default the top-of-page format is the name of the filehandle with -"_TOP" appended, but it may be dynamically set to the format of your -choice by assigning the name to the C<$^> variable while the filehandle is -selected. The number of lines remaining on the current page is in -variable C<$->, which can be set to C<0> to force a new page. +Top of form processing is handled automatically: if there is insufficient +room on the current page for the formatted record, the page is advanced by +writing a form feed, a special top-of-page format is used to format the new +page header before the record is written. By default, the top-of-page +format is the name of the filehandle with "_TOP" appended. This would be a +problem with autovivified filehandles, but it may be dynamically set to the +format of your choice by assigning the name to the C<$^> variable while +that filehandle is selected. The number of lines remaining on the current +page is in variable C<$->, which can be set to C<0> to force a new page. If FILEHANDLE is unspecified, output goes to the current default output channel, which starts out as STDOUT but may be changed by the @@ -7735,3 +8057,5 @@ The transliteration operator. Same as C<tr///>. See L<perlop/"Quote and Quote-like Operators">. =back + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlrepository.pod b/Master/tlpkg/tlperl/lib/pods/perlgit.pod index 3f1bb8adfc9..eac7bb84b5e 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlrepository.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlgit.pod @@ -1,130 +1,41 @@ +=encoding utf8 + =for comment Consistent formatting of this file is achieved with: - perl ./Porting/podtidy pod/perlrepository.pod + perl ./Porting/podtidy pod/perlgit.pod =head1 NAME -perlrepository - Using the Perl source repository - -=head1 SYNOPSIS - -All of Perl's source code is kept centrally in a Git repository at -I<perl5.git.perl.org>. The repository contains many Perl revisions from -Perl 1 onwards and all the revisions from Perforce, the version control -system we were using previously. This repository is accessible in -different ways. - -The full repository takes up about 80MB of disk space. A check out of -the blead branch (that is, the main development branch, which contains -bleadperl, the development version of perl 5) takes up about 160MB of -disk space (including the repository). A build of bleadperl takes up -about 200MB (including the repository and the check out). - -=head1 Getting access to the repository - -=head2 Read access via the web - -You may access the repository over the web. This allows you to browse -the tree, see recent commits, subscribe to RSS feeds for the changes, -search for particular commits and more. You may access it at: - - http://perl5.git.perl.org/perl.git - -A mirror of the repository is found at: - - http://github.com/mirrors/perl - -=head2 Read access via Git - -You will need a copy of Git for your computer. You can fetch a copy of -the repository using the Git protocol (which uses port 9418): - - % git clone git://perl5.git.perl.org/perl.git perl-git - -This clones the repository and makes a local copy in the F<perl-git> -directory. +perlgit - Detailed information about git and the Perl repository -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 at least 4x slower): +=head1 DESCRIPTION - % git clone http://perl5.git.perl.org/perl.git perl-http +This document provides details on using git to develop Perl. If you are +just interested in working on a quick patch, see L<perlhack> first. +This document is intended for people who are regular contributors to +Perl, including those with write access to the git repository. -This clones the repository and makes a local copy in the F<perl-http> -directory. +=head1 CLONING THE REPOSITORY -=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/perl.git perl-ssh - -This clones the repository and makes a local copy in the F<perl-ssh> -directory. - -If you cloned using the git protocol, which is faster than ssh, then -you will need to modify the URL for the origin remote to enable -pushing. To do that edit F<.git/config> with git-config(1) like -this: - - % git config remote.origin.url ssh://perl5.git.perl.org/perl.git - -You can also set up your user name and e-mail address. Most people do -this once globally in their F<~/.gitconfig> by doing something like: - - % git config --global user.name "Ævar Arnfjörð Bjarmason" - % git config --global user.email avarab@gmail.com - -However if you'd like to override that just for perl then execute then -execute something like the following in F<perl-git>: +All of Perl's source code is kept centrally in a Git repository at +I<perl5.git.perl.org>. - % git config user.email avar@cpan.org +You can make a read-only clone of the repository by running: -It is also possible to keep C<origin> as a git remote, and add a new -remote for ssh access: + % git clone git://perl5.git.perl.org/perl.git perl - % git remote add camel perl5.git.perl.org:/perl.git +This uses the git protocol (port 9418). -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: +If you cannot use the git protocol for firewall reasons, you can also +clone via http, though this is much slower: - % git fetch camel - % git push camel + % git clone http://perl5.git.perl.org/perl.git perl -The C<fetch> command just updates the C<camel> refs, as the objects -themselves should have been fetched when pulling from C<origin>. - -=head2 A note on camel and dromedary - -The committers have SSH access to the two servers that serve -C<perl5.git.perl.org>. One is C<perl5.git.perl.org> itself (I<camel>), -which is the 'master' repository. The second one is -C<users.perl5.git.perl.org> (I<dromedary>), which can be used for -general testing and development. Dromedary syncs the git tree from -camel every few minutes, you should not push there. Both machines also -have a full CPAN mirror in /srv/CPAN, please use this. To share files -with the general public, dromedary serves your ~/public_html/ as -C<http://users.perl5.git.perl.org/~yourlogin/> - -These hosts have fairly strict firewalls to the outside. Outgoing, only -rsync, ssh and git are allowed. For http and ftp, you can use -http://webproxy:3128 as proxy. Incoming, the firewall tries to detect -attacks and blocks IP addresses with suspicious activity. This -sometimes (but very rarely) has false positives and you might get -blocked. The quickest way to get unblocked is to notify the admins. - -These two boxes are owned, hosted, and operated by booking.com. You can -reach the sysadmins in #p5p on irc.perl.org or via mail to -C<perl5-porters@perl.org> - -=head1 Overview of the repository +=head1 WORKING WITH 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. +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 @@ -203,12 +114,12 @@ how to change things. For instance the following: # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # - # modified: pod/perlrepository.pod + # modified: pod/perlgit.pod # # Changed but not updated: # (use "git add <file>..." to update what will be committed) # - # modified: pod/perlrepository.pod + # modified: pod/perlgit.pod # # Untracked files: # (use "git add <file>..." to include in what will be committed) @@ -224,64 +135,20 @@ 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 that you'd like to commit all the changes you've just made as a -a single atomic unit, run this command: - - % git commit -a - -(That C<-a> tells git to add every file you've changed to this commit. -New files aren't automatically added to your commit when you use C<commit --a> If you want to add files or to commit some, but not all of your -changes, have a look at the documentation for C<git add>.) - -Git will start up your favorite text editor, so that you can craft a -commit message for your change. See L</Commit message> below for more -information about what makes a good commit message. - -Once you've finished writing your commit message and exited your editor, -git will write your change to disk and tell you something like this: - - Created commit daf8e63: explain git status and stuff about remotes - 1 files changed, 83 insertions(+), 3 deletions(-) - - -If you re-run C<git status>, you should 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 +=head2 Patch workflow -If you have a patch in mind for Perl, you should first get a copy of -the repository: +First, please read L<perlhack> for details on hacking the Perl core. +That document covers many details on how to create a good patch. - % 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: +If you already have a Perl repository, you should ensure that you're on +the I<blead> branch, and your repository is up to date: % git checkout blead % git pull It's preferable to patch against the latest blead version, since this is where new development occurs for all changes other than critical bug -fixes. Critical bug fix patches should be made against the relevant +fixes. Critical bug fix patches should be made against the relevant maint branches, or should be submitted with a note indicating all the branches where the fix should be applied. @@ -297,11 +164,10 @@ which is the short form of Creating a topic branch makes it easier for the maintainers to rebase or merge back into the master blead for a more linear history. If you -don't work on a topic branch the maintainer has to manually cherry -pick your changes onto blead before they can be applied. +don't work on a topic branch the maintainer has to manually cherry pick +your changes onto blead before they can be applied. -That'll get you scolded on perl5-porters, so don't do that. Be -Awesome. +That'll get you scolded on perl5-porters, so don't do that. Be Awesome. Then make your changes. For example, if Leon Brocard changes his name to Orange Brocard, we should change his name in the AUTHORS file: @@ -341,6 +207,43 @@ Now commit your change locally: Created commit 6196c1d: Rename Leon Brocard to Orange Brocard 1 files changed, 1 insertions(+), 1 deletions(-) +The C<-a> option is used to include all files that git tracks that you +have changed. If at this time, you only want to commit some of the +files you have worked on, you can omit the C<-a> and use the command +C<S<git add I<FILE ...>>> before doing the commit. C<S<git add +--interactive>> allows you to even just commit portions of files +instead of all the changes in them. + +The C<-m> option is used to specify the commit message. If you omit it, +git will open a text editor for you to compose the message +interactively. This is useful when the changes are more complex than +the sample given here, and, depending on the editor, to know that the +first line of the commit message doesn't exceed the 50 character legal +maximum. + +Once you've finished writing your commit message and exited your +editor, git will write your change to disk and tell you something like +this: + + Created commit daf8e63: explain git status and stuff about remotes + 1 files changed, 83 insertions(+), 3 deletions(-) + +If you re-run C<git status>, you should 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. + You can examine your last commit with: % git show HEAD @@ -358,8 +261,9 @@ Now you should create a patch file for all your local changes: You should now send an email to to L<perlbug@perl.org|mailto:perlbug@perl.org> with a description of your changes, and include this patch file as an attachment. In addition to -being tracked by RT, mail to perlbug will automatically be forwarded -to perl5-porters. You should only send patches to +being tracked by RT, mail to perlbug will automatically be forwarded to +perl5-porters (with manual moderation, so please be patient). You +should only send patches to L<perl5-porters@perl.org|mailto:perl5-porters@perl.org> directly if the patch is not ready to be applied, but intended for discussion. @@ -375,14 +279,56 @@ If you want to delete your temporary branch, you may do so with: % git branch -D orange Deleted branch orange. +=head2 Committing your changes + +Assuming that you'd like to commit all the changes you've made as a +single atomic unit, run this command: + + % git commit -a + +(That C<-a> tells git to add every file you've changed to this commit. +New files aren't automatically added to your commit when you use +C<commit -a> If you want to add files or to commit some, but not all of +your changes, have a look at the documentation for C<git add>.) + +Git will start up your favorite text editor, so that you can craft a +commit message for your change. See L<perlhack/Commit message> for more +information about what makes a good commit message. + +Once you've finished writing your commit message and exited your +editor, git will write your change to disk and tell you something like +this: + + Created commit daf8e63: explain git status and stuff about remotes + 1 files changed, 83 insertions(+), 3 deletions(-) + +If you re-run C<git status>, you should 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. + =head2 Using git to send patch emails +Please read L<perlhack> first in order to figure out where your patches +should be sent. + In your ~/git/perl repository, set the destination email to perl's bug tracker: $ git config sendemail.to perlbug@perl.org -Or maybe perl5-porters (discussed above): +Or maybe perl5-porters: $ git config sendemail.to perl5-porters@perl.org @@ -399,7 +345,7 @@ send email via a gmail account: $ git config --global sendemail.smtpuser YOURUSERNAME@gmail.com With this configuration, you will be prompted for your gmail password -when you run 'git send-email'. You can also configure +when you run 'git send-email'. You can also configure C<sendemail.smtppass> with your password if you don't care about having your password in the .gitconfig file. @@ -407,223 +353,15 @@ your password in the .gitconfig file. Be aware that many files in the distribution are derivative--avoid patching them, because git won't see the changes to them, and the build -process will overwrite them. Patch the originals instead. Most +process will overwrite them. Patch the originals instead. Most utilities (like perldoc) are in this category, i.e. patch -F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't create -patches for files under $src_root/ext from their copies found in -$install_root/lib. If you are unsure about the proper location of a +F<utils/perldoc.PL> rather than F<utils/perldoc>. Similarly, don't +create patches for files under $src_root/ext from their copies found in +$install_root/lib. If you are unsure about the proper location of a file that may have gotten copied while building the source distribution, consult the C<MANIFEST>. -As a special case, several files are regenerated by 'make regen' if -your patch alters C<embed.fnc>. These are needed for compilation, but -are included in the distribution so that you can build perl without -needing another perl to generate the files. You must test with these -regenerated files, but it is preferred that you instead note that -'make regen is needed' in both the email and the commit message, and -submit your patch without them. If you're submitting a series of -patches, it might be best to submit the regenerated changes -immediately after the source-changes that caused them, so as to have -as little effect as possible on the bisectability of your patchset. - -=for XXX -What should we recommend about binary files now? Do we need anything? - -=head2 Getting your patch accepted - -If you are submitting a code patch there are several things that -you need to do. - -=over 4 - -=item Commit message - -As you craft each patch you intend to submit to the Perl core, it's -important to write a good commit message. - -The first line of the commit message should be a short description and -should skip the full stop. It should be no longer than the subject -line of an E-Mail, 50 characters being a good rule of thumb. - -A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ..) will -only display the first line (cut off at 50 characters) when presenting -commit summaries. - -The commit message should include description of the problem that the -patch corrects or new functionality that the patch adds. - -As a general rule of thumb, your commit message should let a programmer -with a reasonable familiarity with the Perl core quickly understand what -you were trying to do, how you were trying to do it and why the change -matters to Perl. - -=over 4 - -=item What - -Your commit message should describe what part of the Perl core you're -changing and what you expect your patch to do. - -=item Why - -Perhaps most importantly, your commit message should describe why the -change you are making is important. When someone looks at your change -in six months or six years, your intent should be clear. If you're -deprecating a feature with the intent of later simplifying another bit -of code, say so. If you're fixing a performance problem or adding a new -feature to support some other bit of the core, mention that. - -=item How - -While it's not necessary for documentation changes, new tests or -trivial patches, it's often worth explaining how your change works. -Even if it's clear to you today, it may not be clear to a porter next -month or next year. - -=back - -A commit message isn't intended to take the place of comments in your -code. Commit messages should describe the change you made, while code -comments should describe the current state of the code. If you've just -implemented a new feature, complete with doc, tests and well-commented -code, a brief commit message will often suffice. If, however, you've -just changed a single character deep in the parser or lexer, you might -need to write a small novel to ensure that future readers understand -what you did and why you did it. - -=item Comments, Comments, Comments - -Be sure to adequately comment your code. While commenting every line -is unnecessary, anything that takes advantage of side effects of -operators, that creates changes that will be felt outside of the -function being patched, or that others may find confusing should be -documented. If you are going to err, it is better to err on the side -of adding too many comments than too few. - -=item Style - -In general, please follow the particular style of the code you are -patching. - -In particular, follow these general guidelines for patching Perl -sources: - - 8-wide tabs (no exceptions!) - 4-wide indents for code, 2-wide indents for nested CPP #defines - try hard not to exceed 79-columns - ANSI C prototypes - uncuddled elses and "K&R" style for indenting control constructs - no C++ style (//) comments - mark places that need to be revisited with XXX (and revisit often!) - opening brace lines up with "if" when conditional spans multiple - lines; should be at end-of-line otherwise - in function definitions, name starts in column 0 (return value is on - previous line) - single space after keywords that are followed by parens, no space - between function name and following paren - avoid assignments in conditionals, but if they're unavoidable, use - extra paren, e.g. "if (a && (b = c)) ..." - "return foo;" rather than "return(foo);" - "if (!foo) ..." rather than "if (foo == FALSE) ..." etc. - -=item Testsuite - -If your patch changes code (rather than just changing documentation) you -should also include one or more test cases which illustrate the bug you're -fixing or validate the new functionality you're adding. In general, -you should update an existing test file rather than create a new one. - -Your testsuite additions should generally follow these guidelines -(courtesy of Gurusamy Sarathy <gsar@activestate.com>): - - Know what you're testing. Read the docs, and the source. - Tend to fail, not succeed. - Interpret results strictly. - Use unrelated features (this will flush out bizarre interactions). - Use non-standard idioms (otherwise you are not testing TIMTOWTDI). - Avoid using hardcoded test numbers whenever possible (the - EXPECTED/GOT found in t/op/tie.t is much more maintainable, - and gives better failure reports). - Give meaningful error messages when a test fails. - Avoid using qx// and system() unless you are testing for them. If you - do use them, make sure that you cover _all_ perl platforms. - Unlink any temporary files you create. - Promote unforeseen warnings to errors with $SIG{__WARN__}. - Be sure to use the libraries and modules shipped with the version - being tested, not those that were already installed. - Add comments to the code explaining what you are testing for. - Make updating the '1..42' string unnecessary. Or make sure that - you update it. - Test _all_ behaviors of a given operator, library, or function: - - All optional arguments - - Return values in various contexts (boolean, scalar, list, lvalue) - - Use both global and lexical variables - - Don't forget the exceptional, pathological cases. - -=back - -=head1 Accepting a patch - -If you have received a patch file generated using the above section, -you should try out the patch. - -First we need to create a temporary new branch for these changes and -switch into it: - - % git checkout -b experimental - -Patches that were formatted by C<git format-patch> are applied with -C<git am>: - - % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch - Applying Rename Leon Brocard to Orange Brocard - -If just a raw diff is provided, it is also possible use this two-step -process: - - % git apply bugfix.diff - % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>" - -Now we can inspect the change: - - % git show HEAD - commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 - Author: Leon Brocard <acme@astray.com> - Date: Fri Dec 19 17:02:59 2008 +0000 - - Rename Leon Brocard to Orange Brocard - - diff --git a/AUTHORS b/AUTHORS - index 293dd70..722c93e 100644 - --- a/AUTHORS - +++ b/AUTHORS - @@ -541,7 +541,7 @@ Lars Hecking <lhecking@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 +=head2 Cleaning a working directory The command C<git clean> can with varying arguments be used as a replacement for C<make clean>. @@ -645,19 +383,27 @@ checkout> and give it a list of files to be reverted, or C<git checkout If you want to cancel one or several commits, you can use C<git reset>. -=head1 Bisecting +=head2 Bisecting C<git> provides a built-in way to determine, with a binary search in the history, which commit should be blamed for introducing a given bug. Suppose that we have a script F<~/testcase.pl> that exits with C<0> -when some behaviour is correct, and with C<1> when it's faulty. You need -an helper script that automates building C<perl> and running the +when some behaviour is correct, and with C<1> when it's faulty. You +need an helper script that automates building C<perl> and running the testcase: % cat ~/run #!/bin/sh git clean -dxf + + # If you get './makedepend: 1: Syntax error: Unterminated quoted + # string' when bisecting versions of perl older than 5.9.5 this hack + # will work around the bug in makedepend.SH which was fixed in + # version 96a8704c. Make sure to comment out `git checkout makedepend.SH' + # below too. + git show blead:makedepend.SH > makedepend.SH + # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line # if Encode is not needed for the test, you can speed up the bisect by # excluding it from the runs with -Dnoextensions=Encode @@ -666,11 +412,12 @@ testcase: # Correct makefile for newer GNU gcc perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile # if you just need miniperl, replace test_prep with miniperl - make -j4 test_prep + make test_prep [ -x ./perl ] || exit 125 ./perl -Ilib ~/testcase.pl ret=$? [ $ret -gt 127 ] && ret=127 + # git checkout makedepend.SH git clean -dxf exit $ret @@ -719,69 +466,98 @@ 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 Topic branches and rewriting history -=head1 Submitting a patch via GitHub - -GitHub is a website that makes it easy to fork and publish projects -with Git. First you should set up a GitHub account and log in. - -Perl's git repository is mirrored on GitHub at this page: - - http://github.com/mirrors/perl/tree/blead - -Visit the page and click the "fork" button. This clones the Perl git -repository for you and provides you with "Your Clone URL" from which -you should clone: - - % git clone git@github.com:USERNAME/perl.git perl-github +Individual committers should create topic branches under +B<yourname>/B<some_descriptive_name>. Other committers should check +with a topic branch's creator before making any change to it. -The same patch as above, using github might look like this: +The simplest way to create a remote topic branch that works on all +versions of git is to push the current head as a new branch on the +remote, then check it out locally: - % cd perl-github - % git remote add upstream git://perl5.git.perl.org/perl.git - % git pull upstream blead - % git checkout -b orange - % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS - % git commit -a -m 'Rename Leon Brocard to Orange Brocard' - % git push origin orange + $ branch="$yourname/$some_descriptive_name" + $ git push origin HEAD:$branch + $ git checkout -b $branch origin/$branch -The orange branch has been pushed to GitHub, so you should now send an -email (see L</Submitting a patch>) with a description of your changes -and the following information: +Users of git 1.7 or newer can do it in a more obvious manner: - http://github.com/USERNAME/perl/tree/orange - git@github.com:USERNAME/perl.git branch orange + $ branch="$yourname/$some_descriptive_name" + $ git checkout -b $branch + $ git push origin -u $branch -=head1 Merging from a branch via GitHub +If you are not the creator of B<yourname>/B<some_descriptive_name>, you +might sometimes find that the original author has edited the branch's +history. There are lots of good reasons for this. Sometimes, an author +might simply be rebasing the branch onto a newer source point. +Sometimes, an author might have found an error in an early commit which +they wanted to fix before merging the branch to blead. -If someone has provided a branch via GitHub and you are a committer, -you should use the following in your perl-ssh directory: +Currently the master repository is configured to forbid +non-fast-forward merges. This means that the branches within can not be +rebased and pushed as a single step. - % git remote add dandv git://github.com/dandv/perl.git - % git fetch dandv +The only way you will ever be allowed to rebase or modify the history +of a pushed branch is to delete it and push it as a new branch under +the same name. Please think carefully about doing this. It may be +better to sequentially rename your branches so that it is easier for +others working with you to cherry-pick their local changes onto the new +version. (XXX: needs explanation). -Now you can see the differences between the branch and blead: +If you want to rebase a personal topic branch, you will have to delete +your existing topic branch and push as a new version of it. You can do +this via the following formula (see the explanation about C<refspec>'s +in the git push documentation for details) after you have rebased your +branch: - % git diff dandv/blead + # first rebase + $ git checkout $user/$topic + $ git fetch + $ git rebase origin/blead -And you can see the commits: + # then "delete-and-push" + $ git push origin :$user/$topic + $ git push origin $user/$topic - % git log dandv/blead +B<NOTE:> it is forbidden at the repository level to delete any of the +"primary" branches. That is any branch matching +C<m!^(blead|maint|perl)!>. Any attempt to do so will result in git +producing an error like this: -If you approve of a specific commit, you can cherry pick it: + $ git push origin :blead + *** It is forbidden to delete blead/maint branches in this repository + error: hooks/update exited with error code 1 + error: hook declined to update refs/heads/blead + To ssh://perl5.git.perl.org/perl + ! [remote rejected] blead (hook declined) + error: failed to push some refs to 'ssh://perl5.git.perl.org/perl' - % git cherry-pick 3adac458cb1c1d41af47fc66e67b49c8dec2323f +As a matter of policy we do B<not> edit the history of the blead and +maint-* branches. If a typo (or worse) sneaks into a commit to blead or +maint-*, we'll fix it in another commit. The only types of updates +allowed on these branches are "fast-forward's", where all history is +preserved. -Or you could just merge the whole branch if you like it all: +Annotated tags in the canonical perl.git repository will never be +deleted or modified. Think long and hard about whether you want to push +a local tag to perl.git before doing so. (Pushing unannotated tags is +not allowed.) - % git merge dandv/blead +=head3 Grafts -And then push back to the repository: +The perl history contains one mistake which was not caught in the +conversion: a merge was recorded in the history between blead and +maint-5.10 where no merge actually occurred. Due to the nature of git, +this is now impossible to fix in the public repository. You can remove +this mis-merge locally by adding the following line to your +C<.git/info/grafts> file: - % git push + 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930 +It is particularly important to have this graft line if any bisecting +is done in the area of the "merge" in question. -=head1 Topic branches and rewriting history +=head2 Topic branches and rewriting history Individual committers should create topic branches under B<yourname>/B<some_descriptive_name>. Other committers should check @@ -809,8 +585,8 @@ Sometimes, an author might have found an error in an early commit which they wanted to fix before merging the branch to blead. Currently the master repository is configured to forbid -non-fast-forward merges. This means that the branches within can not -be rebased and pushed as a single step. +non-fast-forward merges. This means that the branches within can not be +rebased and pushed as a single step. The only way you will ever be allowed to rebase or modify the history of a pushed branch is to delete it and push it as a new branch under @@ -858,10 +634,145 @@ deleted or modified. Think long and hard about whether you want to push a local tag to perl.git before doing so. (Pushing unannotated tags is not allowed.) -=head1 Committing to maintenance versions +=head1 WRITE ACCESS TO THE GIT REPOSITORY + +Once you have write access, you will need to modify the URL for the +origin remote to enable pushing. Edit F<.git/config> with the +git-config(1) command: + + % git config remote.origin.url ssh://perl5.git.perl.org/perl.git + +You can also set up your user name and e-mail address. Most people do +this once globally in their F<~/.gitconfig> by doing something like: + + % git config --global user.name "Ævar Arnfjörð Bjarmason" + % git config --global user.email avarab@gmail.com + +However if you'd like to override that just for perl then execute then +execute something like the following in F<perl>: + + % git config user.email avar@cpan.org + +It is also possible to keep C<origin> as a git remote, and add a new +remote for ssh access: + + % git remote add camel perl5.git.perl.org:/perl.git + +This allows you to update your local repository by pulling from +C<origin>, which is faster and doesn't require you to authenticate, and +to push your changes back with the C<camel> remote: + + % git fetch camel + % git push camel + +The C<fetch> command just updates the C<camel> refs, as the objects +themselves should have been fetched when pulling from C<origin>. +=head1 Accepting a patch + +If you have received a patch file generated using the above section, +you should try out the patch. + +First we need to create a temporary new branch for these changes and +switch into it: + + % git checkout -b experimental + +Patches that were formatted by C<git format-patch> are applied with +C<git am>: + + % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch + Applying Rename Leon Brocard to Orange Brocard + +If just a raw diff is provided, it is also possible use this two-step +process: + + % git apply bugfix.diff + % git commit -a -m "Some fixing" --author="That Guy <that.guy@internets.com>" + +Now we can inspect the change: + + % git show HEAD + commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 + Author: Leon Brocard <acme@astray.com> + Date: Fri Dec 19 17:02:59 2008 +0000 + + Rename Leon Brocard to Orange Brocard + + diff --git a/AUTHORS b/AUTHORS + index 293dd70..722c93e 100644 + --- a/AUTHORS + +++ b/AUTHORS + @@ -541,7 +541,7 @@ Lars Hecking <lhecking@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. + +=head2 Committing to blead -Maintenance versions should only be altered to add critical bug -fixes, see L<perlpolicy>. +The 'blead' branch will become the next production release of Perl. + +Before pushing I<any> local change to blead, it's incredibly important +that you do a few things, lest other committers come after you with +pitchforks and torches: + +=over + +=item * + +Make sure you have a good commit message. See L<perlhack/Commit +message> for details. + +=item * + +Run the test suite. You might not think that one typo fix would break a +test file. You'd be wrong. Here's an example of where not running the +suite caused problems. A patch was submitted that added a couple of +tests to an existing .t. It couldn't possibly affect anything else, so +no need to test beyond the single affected .t, right? But, the +submitter's email address had changed since the last of their +submissions, and this caused other tests to fail. Running the test +target given in the next item would have caught this problem. + +=item * + +If you don't run the full test suite, at least C<make test_porting>. +This will run basic sanity checks. To see which sanity checks, have a +look in F<t/porting>. + +=item * + +If you make any changes that affect miniperl or core routines that have +different code paths for miniperl, be sure to run C<make minitest>. +This will catch problems that even the full test suite will not catch +because it runs a subset of tests under miniperl rather than perl. + +=back + +=head2 Committing to maintenance versions + +Maintenance versions should only be altered to add critical bug fixes, +see L<perlpolicy>. To commit to a maintenance version of perl, you need to create a local tracking branch: @@ -877,12 +788,15 @@ 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 Grafts +Before pushing any change to a maint version, make sure you've +satisfied the steps in L</Committing to blead> above. + +=head2 Grafts The perl history contains one mistake which was not caught in the conversion: a merge was recorded in the history between blead and -maint-5.10 where no merge actually occurred. Due to the nature of git, -this is now impossible to fix in the public repository. You can remove +maint-5.10 where no merge actually occurred. Due to the nature of git, +this is now impossible to fix in the public repository. You can remove this mis-merge locally by adding the following line to your C<.git/info/grafts> file: @@ -891,18 +805,54 @@ C<.git/info/grafts> file: It is particularly important to have this graft line if any bisecting is done in the area of the "merge" in question. -=head1 SEE ALSO +=head2 Merging from a branch via GitHub -=over +While we don't encourage the submission of patches via GitHub, that +will still happen. Here is a guide to merging patches from a GitHub +repository. -=item * + % git remote add avar git://github.com/avar/perl.git + % git fetch avar -The git documentation, accessible via the C<git help> command +Now you can see the differences between the branch and blead: -=item * + % git diff avar/orange -L<perlpolicy> - Perl core development policy +And you can see the commits: -=back + % git log avar/orange + +If you approve of a specific commit, you can cherry pick it: -=cut + % git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae + +Or you could just merge the whole branch if you like it all: + + % git merge avar/orange + +And then push back to the repository: + + % git push + +=head2 A note on camel and dromedary + +The committers have SSH access to the two servers that serve +C<perl5.git.perl.org>. One is C<perl5.git.perl.org> itself (I<camel>), +which is the 'master' repository. The second one is +C<users.perl5.git.perl.org> (I<dromedary>), which can be used for +general testing and development. Dromedary syncs the git tree from +camel every few minutes, you should not push there. Both machines also +have a full CPAN mirror in /srv/CPAN, please use this. To share files +with the general public, dromedary serves your ~/public_html/ as +C<http://users.perl5.git.perl.org/~yourlogin/> + +These hosts have fairly strict firewalls to the outside. Outgoing, only +rsync, ssh and git are allowed. For http and ftp, you can use +http://webproxy:3128 as proxy. Incoming, the firewall tries to detect +attacks and blocks IP addresses with suspicious activity. This +sometimes (but very rarely) has false positives and you might get +blocked. The quickest way to get unblocked is to notify the admins. + +These two boxes are owned, hosted, and operated by booking.com. You can +reach the sysadmins in #p5p on irc.perl.org or via mail to +C<perl5-porters@perl.org>. diff --git a/Master/tlpkg/tlperl/lib/pods/perlglossary.pod b/Master/tlpkg/tlperl/lib/pods/perlglossary.pod index b44fcd447f9..639ce3349f8 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlglossary.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlglossary.pod @@ -234,12 +234,14 @@ some of its high-level ideas. =item backreference A substring L<captured|/capturing> by a subpattern within -unadorned parentheses in a L</regex>. Backslashed decimal numbers -(C<\1>, C<\2>, etc.) later in the same pattern refer back to the -corresponding subpattern in the current match. Outside the pattern, +unadorned parentheses in a L</regex>, also referred to as a capture group. The +sequences (C<\g1>, C<\g2>, etc.) later in the same pattern refer back to +the corresponding subpattern in the current match. Outside the pattern, the numbered variables (C<$1>, C<$2>, etc.) continue to refer to these same values, as long as the pattern was the last successful match of -the current dynamic scope. +the current dynamic scope. C<\g{-1}> can be used to refer to a group by +relative rather than absolute position; and groups can be also be named, and +referred to later by name rather than number. See L<perlre/"Capture groups">. =item backtracking @@ -458,10 +460,16 @@ handler when some event of interest transpires. Reduced to a standard form to facilitate comparison. +=item capture buffer, capture group + +These two terms are synonymous: +a L<captured substring|/capturing> by a regex subpattern. + =item capturing The use of parentheses around a L</subpattern> in a L</regular -expression> to store the matched L</substring> as a L</backreference>. +expression> to store the matched L</substring> as a L</backreference> +or L<capture group|/capture buffer, capture group>. (Captured strings are also returned as a list in L</list context>.) =item character @@ -499,7 +507,7 @@ the class (its L<objects|/object>). See also L</inheritance>. =item class method -A L</method> whose L</invocant> is a L</package> name, not an +A L</method> whose L</invocand> is a L</package> name, not an L</object> reference. A method associated with the class as a whole. =item client @@ -537,6 +545,17 @@ A system that writes code for you in a low-level language, such as code to implement the backend of a compiler. See L</program generator>. +=item code point + +The position of a character in a character set encoding. The character +C<NULL> is almost certainly at the zeroth position in all character +sets, so its code point is 0. The code point for the C<SPACE> +character in the ASCII character set is 0x20, or 32 decimal; in EBCDIC +it is 0x40, or 64 decimal. The L<ord|perlfunc/ord> function returns +the code point of a character. + +"code position" and "ordinal" mean the same thing as "code point". + =item code subpattern A L</regular expression> subpattern whose real purpose is to execute @@ -875,7 +894,7 @@ will be called a "binary-only" distribution. =item (to be) dropped modules -When Perl 5 was first released (see L<perlhistory>), several modules were +When Perl 5 was first released (see L<perlhist>), several modules were included, which have now fallen out of common use. It has been suggested that these modules should be removed, since the distribution became rather large, and the common criterion for new module additions is now limited to @@ -1221,6 +1240,12 @@ Someone like Larry, or one of his peculiar friends. Also refers to the strange prefixes that Perl requires as noun markers on its variables. +=back + +=head2 G + +=over 4 + =item garbage collection A misnamed feature--it should be called, "expecting your mother to @@ -1232,12 +1257,6 @@ any comfort, when your interpreter exits, a "real" garbage collector runs to make sure everything is cleaned up if you've been messy with circular references and such.) -=back - -=head2 G - -=over 4 - =item GID Group ID--in Unix, the numeric group ID that the L</operating system> @@ -1451,7 +1470,7 @@ Perl, C<print STDOUT "$foo\n";> can be understood as "verb indirect-object object" where L</STDOUT> is the recipient of the L<print|perlfunc/print> action, and C<"$foo"> is the object being printed. Similarly, when invoking a L</method>, you might place the -invocant between the method and its arguments: +invocand between the method and its arguments: $gollum = new Pathetic::Creature "Smeagol"; give $gollum "Fisssssh!"; @@ -1529,11 +1548,11 @@ of compiler that takes a program and turns it into a more executable form (L<syntax trees|/syntax tree>) within the I<perl> process itself, which the Perl L</run time> system then interprets. -=item invocant +=item invocand The agent on whose behalf a L</method> is invoked. In a L</class> -method, the invocant is a package name. In an L</instance> method, -the invocant is an object reference. +method, the invocand is a package name. In an L</instance> method, +the invocand is an object reference. =item invocation @@ -2106,6 +2125,10 @@ L</pragma>. See either L<switches|/switch> or L</regular expression modifier>. +=item ordinal + +Another name for L</code point> + =item overloading Giving additional meanings to a symbol or construct. Actually, all @@ -2962,9 +2985,8 @@ L</argument> must be the last switch in a cluster. A program technique that lets you evaluate an L</expression> and then, based on the value of the expression, do a multiway branch to the appropriate piece of code for that value. Also called a "case -structure", named after the similar Pascal construct. Most switch -statements in Perl are spelled C<for>. See L<perlsyn/Basic BLOCKs and -Switch Statements>. +structure", named after the similar Pascal construct. See +L<perlsyn/"Switch statements">. =item symbol @@ -3132,7 +3154,7 @@ to build special tools. Perl is sort of a machine shop. To turn one string representation into another by mapping each character of the source string to its corresponding character in the result string. See -L<perlop/trE<sol>SEARCHLISTE<sol>REPLACEMENTLISTE<sol>cds>. +L<perlop/trE<sol>SEARCHLISTE<sol>REPLACEMENTLISTE<sol>cdsr>. =item trigger diff --git a/Master/tlpkg/tlperl/lib/pods/perlguts.pod b/Master/tlpkg/tlperl/lib/pods/perlguts.pod index b6cec65bbbb..fcf436b7a0c 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlguts.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlguts.pod @@ -539,14 +539,14 @@ in restricted hashes. This caused such hash entries not to appear when iterating over the hash or when checking for the keys with the C<hv_exists> function. -You can run into similar problems when you store C<&PL_sv_true> or -C<&PL_sv_false> into AVs or HVs. Trying to modify such elements +You can run into similar problems when you store C<&PL_sv_yes> or +C<&PL_sv_no> into AVs or HVs. Trying to modify such elements will give you the following error: Modification of a read-only value attempted To make a long story short, you can use the special variables -C<&PL_sv_undef>, C<&PL_sv_true> and C<&PL_sv_false> with AVs and +C<&PL_sv_undef>, C<&PL_sv_yes> and C<&PL_sv_no> with AVs and HVs, but you have to make sure you know what you're doing. Generally, if you want to store an undefined value in an AV @@ -671,11 +671,11 @@ your Perl script, use the following routines, depending on the variable type. AV* get_av("package::varname", GV_ADD); HV* get_hv("package::varname", GV_ADD); -Notice the use of TRUE as the second parameter. The new variable can now +Notice the use of GV_ADD as the second parameter. The new variable can now be set, using the routines appropriate to the data type. There are additional macros whose values may be bitwise OR'ed with the -C<TRUE> argument to enable certain extra features. Those bits are: +C<GV_ADD> argument to enable certain extra features. Those bits are: =over @@ -958,11 +958,17 @@ This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>. To remove the magic from an SV, call the function sv_unmagic: - void sv_unmagic(SV *sv, int type); + int sv_unmagic(SV *sv, int type); The C<type> argument should be equal to the C<how> value when the C<SV> was initially made magical. +However, note that C<sv_unmagic> removes all magic of a certain C<type> from the +C<SV>. If you want to remove only certain magic of a C<type> based on the magic +virtual table, use C<sv_unmagicext> instead: + + int sv_unmagicext(SV *sv, int type, MGVTBL *vtbl); + =head2 Magic Virtual Tables The C<mg_virtual> field in the C<MAGIC> structure is a pointer to an @@ -1125,8 +1131,20 @@ Note that because multiple extensions may be using C<PERL_MAGIC_ext> or C<PERL_MAGIC_uvar> magic, it is important for extensions to take extra care to avoid conflict. Typically only using the magic on objects blessed into the same class as the extension is sufficient. -For C<PERL_MAGIC_ext> magic, it may also be appropriate to add an I32 -'signature' at the top of the private data area and check that. +For C<PERL_MAGIC_ext> magic, it is usually a good idea to define an +C<MGVTBL>, even if all its fields will be C<0>, so that individual +C<MAGIC> pointers can be identified as a particular kind of magic +using their magic virtual table. C<mg_findext> provides an easy way +to do that: + + STATIC MGVTBL my_vtbl = { 0, 0, 0, 0, 0, 0, 0, 0 }; + + MAGIC *mg; + if ((mg = mg_findext(sv, PERL_MAGIC_ext, &my_vtbl))) { + /* this is really ours, not another module's PERL_MAGIC_ext */ + my_priv_data_t *priv = (my_priv_data_t *)mg->mg_ptr; + ... + } Also note that the C<sv_set*()> and C<sv_cat*()> functions described earlier do B<not> invoke 'set' magic on their targets. This must @@ -1142,11 +1160,18 @@ since their implementation handles 'get' magic. =head2 Finding Magic - MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */ + MAGIC *mg_find(SV *sv, int type); /* Finds the magic pointer of that type */ + +This routine returns a pointer to a C<MAGIC> structure stored in the SV. +If the SV does not have that magical feature, C<NULL> is returned. If the +SV has multiple instances of that magical feature, the first one will be +returned. C<mg_findext> can be used to find a C<MAGIC> structure of an SV +based on both it's magic type and it's magic virtual table: -This routine returns a pointer to the C<MAGIC> structure stored in the SV. -If the SV does not have that magical feature, C<NULL> is returned. Also, -if the SV is not of type SVt_PVMG, Perl may core dump. + MAGIC *mg_findext(SV *sv, int type, MGVTBL *vtbl); + +Also, if the SV passed to C<mg_find> or C<mg_findext> is not of type +SVt_PVMG, Perl may core dump. int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen); @@ -1438,6 +1463,8 @@ L</Reference Counts and Mortality>): PUSHs(sv_2mortal(newSVuv(an_unsigned_integer))) PUSHs(sv_2mortal(newSVnv(a_double))) PUSHs(sv_2mortal(newSVpv("Some String",0))) + /* Although the last example is better written as the more efficient: */ + PUSHs(newSVpvs_flags("Some String", SVs_TEMP)) And now the Perl program calling C<tzname>, the two values will be assigned as in: @@ -1821,9 +1848,41 @@ of free()ing (i.e. their type is changed to OP_NULL). After the compile tree for a subroutine (or for an C<eval> or a file) is created, an additional pass over the code is performed. This pass is neither top-down or bottom-up, but in the execution order (with -additional complications for conditionals). These optimizations are -done in the subroutine peep(). Optimizations performed at this stage -are subject to the same restrictions as in the pass 2. +additional complications for conditionals). Optimizations performed +at this stage are subject to the same restrictions as in the pass 2. + +Peephole optimizations are done by calling the function pointed to +by the global variable C<PL_peepp>. By default, C<PL_peepp> just +calls the function pointed to by the global variable C<PL_rpeepp>. +By default, that performs some basic op fixups and optimisations along +the execution-order op chain, and recursively calls C<PL_rpeepp> for +each side chain of ops (resulting from conditionals). Extensions may +provide additional optimisations or fixups, hooking into either the +per-subroutine or recursive stage, like this: + + static peep_t prev_peepp; + static void my_peep(pTHX_ OP *o) + { + /* custom per-subroutine optimisation goes here */ + prev_peepp(o); + /* custom per-subroutine optimisation may also go here */ + } + BOOT: + prev_peepp = PL_peepp; + PL_peepp = my_peep; + + static peep_t prev_rpeepp; + static void my_rpeep(pTHX_ OP *o) + { + OP *orig_o = o; + for(; o; o = o->op_next) { + /* custom per-op optimisation goes here */ + } + prev_rpeepp(orig_o); + } + BOOT: + prev_rpeepp = PL_rpeepp; + PL_rpeepp = my_rpeep; =head2 Pluggable runops @@ -1842,6 +1901,76 @@ file, add the line: This function should be as efficient as possible to keep your programs running as fast as possible. +=head2 Compile-time scope hooks + +As of perl 5.14 it is possible to hook into the compile-time lexical +scope mechanism using C<Perl_blockhook_register>. This is used like +this: + + STATIC void my_start_hook(pTHX_ int full); + STATIC BHK my_hooks; + + BOOT: + BhkENTRY_set(&my_hooks, bhk_start, my_start_hook); + Perl_blockhook_register(aTHX_ &my_hooks); + +This will arrange to have C<my_start_hook> called at the start of +compiling every lexical scope. The available hooks are: + +=over 4 + +=item C<void bhk_start(pTHX_ int full)> + +This is called just after starting a new lexical scope. Note that Perl +code like + + if ($x) { ... } + +creates two scopes: the first starts at the C<(> and has C<full == 1>, +the second starts at the C<{> and has C<full == 0>. Both end at the +C<}>, so calls to C<start> and C<pre/post_end> will match. Anything +pushed onto the save stack by this hook will be popped just before the +scope ends (between the C<pre_> and C<post_end> hooks, in fact). + +=item C<void bhk_pre_end(pTHX_ OP **o)> + +This is called at the end of a lexical scope, just before unwinding the +stack. I<o> is the root of the optree representing the scope; it is a +double pointer so you can replace the OP if you need to. + +=item C<void bhk_post_end(pTHX_ OP **o)> + +This is called at the end of a lexical scope, just after unwinding the +stack. I<o> is as above. Note that it is possible for calls to C<pre_> +and C<post_end> to nest, if there is something on the save stack that +calls string eval. + +=item C<void bhk_eval(pTHX_ OP *const o)> + +This is called just before starting to compile an C<eval STRING>, C<do +FILE>, C<require> or C<use>, after the eval has been set up. I<o> is the +OP that requested the eval, and will normally be an C<OP_ENTEREVAL>, +C<OP_DOFILE> or C<OP_REQUIRE>. + +=back + +Once you have your hook functions, you need a C<BHK> structure to put +them in. It's best to allocate it statically, since there is no way to +free it once it's registered. The function pointers should be inserted +into this structure using the C<BhkENTRY_set> macro, which will also set +flags indicating which entries are valid. If you do need to allocate +your C<BHK> dynamically for some reason, be sure to zero it before you +start. + +Once registered, there is no mechanism to switch these hooks off, so if +that is necessary you will need to do this yourself. An entry in C<%^H> +is probably the best way, so the effect is lexically scoped; however it +is also possible to use the C<BhkDISABLE> and C<BhkENABLE> macros to +temporarily switch entries on and off. You should also be aware that +generally speaking at least one scope will have opened before your +extension is loaded, so you will see some C<pre/post_end> pairs that +didn't have a matching C<start>. + =head1 Examining internal data structures with the C<dump> functions To aid debugging, the source file F<dump.c> contains a number of @@ -2651,10 +2780,79 @@ responsible for adding stack marks if necessary. You should also "register" your op with the Perl interpreter so that it can produce sensible error and warning messages. Since it is possible to have multiple custom ops within the one "logical" op type C<OP_CUSTOM>, -Perl uses the value of C<< o->op_ppaddr >> as a key into the -C<PL_custom_op_descs> and C<PL_custom_op_names> hashes. This means you -need to enter a name and description for your op at the appropriate -place in the C<PL_custom_op_names> and C<PL_custom_op_descs> hashes. +Perl uses the value of C<< o->op_ppaddr >> to determine which custom op +it is dealing with. You should create an C<XOP> structure for each +ppaddr you use, set the properties of the custom op with +C<XopENTRY_set>, and register the structure against the ppaddr using +C<Perl_custom_op_register>. A trivial example might look like: + + static XOP my_xop; + static OP *my_pp(pTHX); + + BOOT: + XopENTRY_set(&my_xop, xop_name, "myxop"); + XopENTRY_set(&my_xop, xop_desc, "Useless custom op"); + Perl_custom_op_register(aTHX_ my_pp, &my_xop); + +The available fields in the structure are: + +=over 4 + +=item xop_name + +A short name for your op. This will be included in some error messages, +and will also be returned as C<< $op->name >> by the L<B|B> module, so +it will appear in the output of module like L<B::Concise|B::Concise>. + +=item xop_desc + +A short description of the function of the op. + +=item xop_class + +Which of the various C<*OP> structures this op uses. This should be one of +the C<OA_*> constants from F<op.h>, namely + +=over 4 + +=item OA_BASEOP + +=item OA_UNOP + +=item OA_BINOP + +=item OA_LOGOP + +=item OA_LISTOP + +=item OA_PMOP + +=item OA_SVOP + +=item OA_PADOP + +=item OA_PVOP_OR_SVOP + +This should be interpreted as 'C<PVOP>' only. The C<_OR_SVOP> is because +the only core C<PVOP>, C<OP_TRANS>, can sometimes be a C<SVOP> instead. + +=item OA_LOOP + +=item OA_COP + +=back + +The other C<OA_*> constants should not be used. + +=item xop_peep + +This member is of type C<Perl_cpeep_t>, which expands to C<void +(*Perl_cpeep_t)(aTHX_ OP *o, OP *oldop)>. If it is set, this function +will be called from C<Perl_rpeep> when ops of this type are encountered +by the peephole optimizer. I<o> is the OP that needs optimizing; +I<oldop> is the previous OP optimized, whose C<op_next> points to I<o>. + +=back C<B::Generate> directly supports the creation of custom ops by name. diff --git a/Master/tlpkg/tlperl/lib/pods/perlhack.pod b/Master/tlpkg/tlperl/lib/pods/perlhack.pod index 844b83b7b05..dbb020f09a7 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlhack.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlhack.pod @@ -1,1993 +1,840 @@ -=head1 NAME +=encoding utf8 -perlhack - How to hack at the Perl internals +=for comment +Consistent formatting of this file is achieved with: + perl ./Porting/podtidy pod/perlhack.pod -=head1 DESCRIPTION +=head1 NAME -This document attempts to explain how Perl development takes place, -and ends with some suggestions for people wanting to become bona fide -porters. +perlhack - How to hack on Perl -The perl5-porters mailing list is where the Perl standard distribution -is maintained and developed. The list can get anywhere from 10 to 150 -messages a day, depending on the heatedness of the debate. Most days -there are two or three patches, extensions, features, or bugs being -discussed at a time. +=head1 DESCRIPTION -A searchable archive of the list is at either: +This document explains how Perl development works. It includes details +about the Perl 5 Porters email list, the Perl repository, the Perlbug +bug tracker, patch guidelines, and commentary on Perl development +philosophy. - http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ +=head1 SUPER QUICK PATCH GUIDE -or - - http://archive.develooper.com/perl5-porters@perl.org/ - -List subscribers (the porters themselves) come in several flavours. -Some are quiet curious lurkers, who rarely pitch in and instead watch -the ongoing development to ensure they're forewarned of new changes or -features in Perl. Some are representatives of vendors, who are there -to make sure that Perl continues to compile and work on their -platforms. Some patch any reported bug that they know how to fix, -some are actively patching their pet area (threads, Win32, the regexp -engine), while others seem to do nothing but complain. In other -words, it's your usual mix of technical people. - -Over this group of porters presides Larry Wall. He has the final word -in what does and does not change in the Perl language. Various -releases of Perl are shepherded by a "pumpking", a porter -responsible for gathering patches, deciding on a patch-by-patch, -feature-by-feature basis what will and will not go into the release. -For instance, Gurusamy Sarathy was the pumpking for the 5.6 release of -Perl, and Jarkko Hietaniemi was the pumpking for the 5.8 release, and -Rafael Garcia-Suarez holds the pumpking crown for the 5.10 release. - -In addition, various people are pumpkings for different things. For -instance, Andy Dougherty and Jarkko Hietaniemi did a grand job as the -I<Configure> pumpkin up till the 5.8 release. For the 5.10 release -H.Merijn Brand took over. - -Larry sees Perl development along the lines of the US government: -there's the Legislature (the porters), the Executive branch (the -pumpkings), and the Supreme Court (Larry). The legislature can -discuss and submit patches to the executive branch all they like, but -the executive branch is free to veto them. Rarely, the Supreme Court -will side with the executive branch over the legislature, or the -legislature over the executive branch. Mostly, however, the -legislature and the executive branch are supposed to get along and -work out their differences without impeachment or court cases. - -You might sometimes see reference to Rule 1 and Rule 2. Larry's power -as Supreme Court is expressed in The Rules: +If you just want to submit a single small patch like a pod fix, a test +for a bug, comment fixes, etc., it's easy! Here's how: =over 4 -=item 1 - -Larry is always by definition right about how Perl should behave. -This means he has final veto power on the core functionality. +=item * Check out the source repository -=item 2 +The perl source is in a git repository. You can clone the repository +with the following command: -Larry is allowed to change his mind about any matter at a later date, -regardless of whether he previously invoked Rule 1. + % git clone git://perl5.git.perl.org/perl.git perl -=back +=item * Make your change -Got that? Larry is always right, even when he was wrong. It's rare -to see either Rule exercised, but they are often alluded to. +Hack, hack, hack. -New features and extensions to the language are contentious, because -the criteria used by the pumpkings, Larry, and other porters to decide -which features should be implemented and incorporated are not codified -in a few small design goals as with some other languages. Instead, -the heuristics are flexible and often difficult to fathom. Here is -one person's list, roughly in decreasing order of importance, of -heuristics that new features have to be weighed against: +=item * Test your change -=over 4 +You can run all the tests with the following commands: -=item Does concept match the general goals of Perl? + % ./Configure -des -Dusedevel + % make test -These haven't been written anywhere in stone, but one approximation -is: +Keep hacking until the tests pass. - 1. Keep it fast, simple, and useful. - 2. Keep features/concepts as orthogonal as possible. - 3. No arbitrary limits (platforms, data sizes, cultures). - 4. Keep it open and exciting to use/patch/advocate Perl everywhere. - 5. Either assimilate new technologies, or build bridges to them. +=item * Commit your change -=item Where is the implementation? +Committing your work will save the change I<on your local system>: -All the talk in the world is useless without an implementation. In -almost every case, the person or people who argue for a new feature -will be expected to be the ones who implement it. Porters capable -of coding new features have their own agendas, and are not available -to implement your (possibly good) idea. + % git commit -a -m 'Commit message goes here' -=item Backwards compatibility +Make sure the commit message describes your change in a single +sentence. For example, "Fixed spelling errors in perlhack.pod". -It's a cardinal sin to break existing Perl programs. New warnings are -contentious--some say that a program that emits warnings is not -broken, while others say it is. Adding keywords has the potential to -break programs, changing the meaning of existing token sequences or -functions might break programs. +=item * Send your change to perlbug -=item Could it be a module instead? +The next step is to submit your patch to the Perl core ticket system +via email. -Perl 5 has extension mechanisms, modules and XS, specifically to avoid -the need to keep changing the Perl interpreter. You can write modules -that export functions, you can give those functions prototypes so they -can be called like built-in functions, you can even write XS code to -mess with the runtime data structures of the Perl interpreter if you -want to implement really complicated things. If it can be done in a -module instead of in the core, it's highly unlikely to be added. +Assuming your patch consists of a single git commit, you can send it to +perlbug with this command line: -=item Is the feature generic enough? + % git format-patch HEAD^1..HEAD + % perlbug -s '[PATCH] `git log --pretty=format:%s HEAD^1..HEAD`' -f 0001-*.patch -Is this something that only the submitter wants added to the language, -or would it be broadly useful? Sometimes, instead of adding a feature -with a tight focus, the porters might decide to wait until someone -implements the more generalized feature. For instance, instead of -implementing a "delayed evaluation" feature, the porters are waiting -for a macro system that would permit delayed evaluation and much more. +The perlbug program will ask you a few questions about your email +address and the patch you're submitting. Once you've answered them you +can submit your patch. -=item Does it potentially introduce new bugs? +=item * Thank you -Radical rewrites of large chunks of the Perl interpreter have the -potential to introduce new bugs. The smaller and more localized the -change, the better. +The porters appreciate the time you spent helping to make Perl better. +Thank you! -=item Does it preclude other desirable features? +=back -A patch is likely to be rejected if it closes off future avenues of -development. For instance, a patch that placed a true and final -interpretation on prototypes is likely to be rejected because there -are still options for the future of prototypes that haven't been -addressed. +=head1 BUG REPORTING -=item Is the implementation robust? +If you want to report a bug in Perl, you must use the F<perlbug> command +line tool. This tool will ensure that your bug report includes all the +relevant system and configuration information. -Good patches (tight code, complete, correct) stand more chance of -going in. Sloppy or incorrect patches might be placed on the back -burner until the pumpking has time to fix, or might be discarded -altogether without further notice. +To browse existing Perl bugs and patches, you can use the web interface +at L<http://rt.perl.org/>. -=item Is the implementation generic enough to be portable? +Please check the archive of the perl5-porters list (see below) and/or +the bug tracking system before submitting a bug report. Often, you'll +find that the bug has been reported already. -The worst patches make use of a system-specific features. It's highly -unlikely that non-portable additions to the Perl language will be -accepted. +You can log in to the bug tracking system and comment on existing bug +reports. If you have additional information regarding an existing bug, +please add it. This will help the porters fix the bug. -=item Is the implementation tested? +=head1 PERL 5 PORTERS -Patches which change behaviour (fixing bugs or introducing new features) -must include regression tests to verify that everything works as expected. -Without tests provided by the original author, how can anyone else changing -perl in the future be sure that they haven't unwittingly broken the behaviour -the patch implements? And without tests, how can the patch's author be -confident that his/her hard work put into the patch won't be accidentally -thrown away by someone in the future? +The perl5-porters (p5p) mailing list is where the Perl standard +distribution is maintained and developed. The people who maintain Perl +are also referred to as the "Perl 5 Porters", or just the "porters". -=item Is there enough documentation? +A searchable archive of the list is available at +L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is +also another archive at +L<http://archive.develooper.com/perl5-porters@perl.org/>. -Patches without documentation are probably ill-thought out or -incomplete. Nothing can be added without documentation, so submitting -a patch for the appropriate manpages as well as the source code is -always a good idea. +=head2 perl-changes mailing list -=item Is there another way to do it? +The perl5-changes mailing list receives a copy of each patch that gets +submitted to the maintenance and development branches of the perl +repository. See L<http://lists.perl.org/list/perl5-changes.html> for +subscription and archive information. -Larry said "Although the Perl Slogan is I<There's More Than One Way -to Do It>, I hesitate to make 10 ways to do something". This is a -tricky heuristic to navigate, though--one man's essential addition is -another man's pointless cruft. +=head1 GETTING THE PERL SOURCE -=item Does it create too much work? +All of Perl's source code is kept centrally in a Git repository at +I<perl5.git.perl.org>. The repository contains many Perl revisions from +Perl 1 onwards and all the revisions from Perforce, the previous +version control system. -Work for the pumpking, work for Perl programmers, work for module -authors, ... Perl is supposed to be easy. +For much more detail on using git with the Perl repository, please see +L<perlgit>. -=item Patches speak louder than words +=head2 Read access via Git -Working code is always preferred to pie-in-the-sky ideas. A patch to -add a feature stands a much higher chance of making it to the language -than does a random feature request, no matter how fervently argued the -request might be. This ties into "Will it be useful?", as the fact -that someone took the time to make the patch demonstrates a strong -desire for the feature. +You will need a copy of Git for your computer. You can fetch a copy of +the repository using the git protocol: -=back + % git clone git://perl5.git.perl.org/perl.git perl -If you're on the list, you might hear the word "core" bandied -around. It refers to the standard distribution. "Hacking on the -core" means you're changing the C source code to the Perl -interpreter. "A core module" is one that ships with Perl. +This clones the repository and makes a local copy in the F<perl> +directory. -=head2 Keeping in sync +If you cannot use the git protocol for firewall reasons, you can also +clone via http, though this is much slower: -The source code to the Perl interpreter, in its different versions, is -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. + % git clone http://perl5.git.perl.org/perl.git perl -How to clone and use the git perl repository is described in L<perlrepository>. +=head2 Read access via the web -You can also choose to use rsync to get a copy of the current source tree -for the bleadperl branch and all maintenance branches: +You may access the repository over the web. This allows you to browse +the tree, see recent commits, subscribe to RSS feeds for the changes, +search for particular commits and more. You may access it at +L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is +found at L<http://github.com/mirrors/perl>. - $ rsync -avz rsync://perl5.git.perl.org/perl-current . - $ rsync -avz rsync://perl5.git.perl.org/perl-5.12.x . - $ rsync -avz rsync://perl5.git.perl.org/perl-5.10.x . - $ rsync -avz rsync://perl5.git.perl.org/perl-5.8.x . - $ rsync -avz rsync://perl5.git.perl.org/perl-5.6.x . - $ rsync -avz rsync://perl5.git.perl.org/perl-5.005xx . +=head2 Read access via rsync -(Add the C<--delete> option to remove leftover files) +You can also choose to use rsync to get a copy of the current source +tree for the bleadperl branch and all maintenance branches: -To get a full list of the available sync points: - - $ rsync perl5.git.perl.org:: + % rsync -avz rsync://perl5.git.perl.org/perl-current . + % rsync -avz rsync://perl5.git.perl.org/perl-5.12.x . + % rsync -avz rsync://perl5.git.perl.org/perl-5.10.x . + % rsync -avz rsync://perl5.git.perl.org/perl-5.8.x . + % rsync -avz rsync://perl5.git.perl.org/perl-5.6.x . + % rsync -avz rsync://perl5.git.perl.org/perl-5.005xx . -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 -and development "branches" of the perl repository. See -http://lists.perl.org/ for subscription information. +(Add the C<--delete> option to remove leftover files.) -If you are a member of the perl5-porters mailing list, it is a good -thing to keep in touch with the most recent changes. If not only to -verify if what you would have posted as a bug report isn't already -solved in the most recent available perl development branch, also -known as perl-current, bleading edge perl, bleedperl or bleadperl. - -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. +To get a full list of the available sync points: -=head2 Perlbug administration + % rsync perl5.git.perl.org:: -There is a single remote administrative interface for modifying bug status, -category, open issues etc. using the B<RT> bugtracker system, maintained -by Robert Spier. Become an administrator, and close any bugs you can get -your sticky mitts on: +=head2 Write access via git - http://bugs.perl.org/ +If you have a commit bit, please see L<perlgit> for more details on +using git. -To email the bug system administrators: +=head1 PATCHING PERL - "perlbug-admin" <perlbug-admin@perl.org> +If you're planning to do more extensive work than a single small fix, +we encourage you to read the documentation below. This will help you +focus your work and make your patches easier to incorporate into the +Perl source. =head2 Submitting patches -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. -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 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, -edit the MANIFEST file accordingly, sort the MANIFEST file using -C<make manisort>, and include those changes as part of your patch. - -Patching documentation also follows the same order: if accepted, a patch -is first applied to B<development>, and if relevant then it's backported -to B<maintenance>. (With an exception for some patches that document -behaviour that only appears in the maintenance branch, but which has -changed in the development version.) - -To report a bug in Perl, use the program I<perlbug> which comes with -Perl (if you can't get Perl to work, send mail to the address -I<perlbug@perl.org> or I<perlbug@perl.com>). Reporting bugs through -I<perlbug> feeds into the automated bug-tracking system, access to -which is provided through the web at http://rt.perl.org/rt3/ . It -often pays to check the archives of the perl5-porters mailing list to -see whether the bug you're reporting has been reported before, and if -so whether it was considered a bug. See above for the location of -the searchable archives. - -The CPAN testers ( http://testers.cpan.org/ ) are a group of -volunteers who test CPAN modules on a variety of platforms. Perl -Smokers ( http://www.nntp.perl.org/group/perl.daily-build and -http://www.nntp.perl.org/group/perl.daily-build.reports/ ) -automatically test Perl source releases on platforms with various -configurations. Both efforts welcome volunteers. In order to get -involved in smoke testing of the perl itself visit -L<http://search.cpan.org/dist/Test-Smoke>. In order to start smoke -testing CPAN modules visit L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> -or L<http://search.cpan.org/dist/minismokebox/> or -L<http://search.cpan.org/dist/CPAN-Reporter/>. +If you have a small patch to submit, please submit it via perlbug. You +can also send email directly to perlbug@perl.org. Please note that +messages sent to perlbug may be held in a moderation queue, so you +won't receive a response immediately. -It's a good idea to read and lurk for a while before chipping in. -That way you'll get to see the dynamic of the conversations, learn the -personalities of the players, and hopefully be better prepared to make -a useful contribution when do you speak up. +You'll know your submission has been processed when you receive an +email from our ticket tracking system. This email will give you a +ticket number. Once your patch has made it to the ticket tracking +system, it will also be sent to the perl5-porters@perl.org list. -If after all this you still think you want to join the perl5-porters -mailing list, send mail to I<perl5-porters-subscribe@perl.org>. To -unsubscribe, send mail to I<perl5-porters-unsubscribe@perl.org>. +Patches are reviewed and discussed on the p5p list. Simple, +uncontroversial patches will usually be applied without any discussion. +When the patch is applied, the ticket will be updated and you will +receive email. In addition, an email will be sent to the p5p list. -To hack on the Perl guts, you'll need to read the following things: +In other cases, the patch will need more work or discussion. That will +happen on the p5p list. -=over 3 +You are encouraged to participate in the discussion and advocate for +your patch. Sometimes your patch may get lost in the shuffle. It's +appropriate to send a reminder email to p5p if no action has been taken +in a month. Please remember that the Perl 5 developers are all +volunteers, and be polite. -=item L<perlguts> +Changes are always applied directly to the main development branch, +called "blead". Some patches may be backported to a maintenance branch. +If you think your patch is appropriate for the maintenance branch, +please explain why when you submit it. -This is of paramount importance, since it's the documentation of what -goes where in the Perl source. Read it over a couple of times and it -might start to make sense - don't worry if it doesn't yet, because the -best way to study it is to read it in conjunction with poking at Perl -source, and we'll do that later on. - -Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very -helpful pictures: - -L<http://search.cpan.org/dist/illguts/> - -=item L<perlxstut> and L<perlxs> - -A working knowledge of XSUB programming is incredibly useful for core -hacking; XSUBs use techniques drawn from the PP code, the portion of the -guts that actually executes a Perl program. It's a lot gentler to learn -those techniques from simple examples and explanation than from the core -itself. - -=item L<perlapi> - -The documentation for the Perl API explains what some of the internal -functions do, as well as the many macros used in the source. +=head2 Getting your patch accepted -=item F<Porting/pumpkin.pod> +If you are submitting a code patch there are several things that you +can do to help the Perl 5 Porters accept your patch. -This is a collection of words of wisdom for a Perl porter; some of it is -only useful to the pumpkin holder, but most of it applies to anyone -wanting to go about Perl development. - -=item The perl5-porters FAQ - -This should be available from http://dev.perl.org/perl5/docs/p5p-faq.html . -It contains hints on reading perl5-porters, information on how -perl5-porters works and how Perl development in general works. - -=back +=head3 Patch style -=head2 Finding Your Way Around +If you used git to check out the Perl source, then using C<git +format-patch> will produce a patch in a style suitable for Perl. The +C<format-patch> command produces one patch file for each commit you +made. If you prefer to send a single patch for all commits, you can use +C<git diff>. -Perl maintenance can be split into a number of areas, and certain people -(pumpkins) will have responsibility for each area. These areas sometimes -correspond to files or directories in the source kit. Among the areas are: + % git co blead + % git pull + % git diff blead my-branch-name -=over 3 +This produces a patch based on the difference between blead and your +current branch. It's important to make sure that blead is up to date +before producing the diff, that's why we call C<git pull> first. -=item Core modules +We strongly recommend that you use git if possible. It will make your +life easier, and ours as well. -Modules shipped as part of the Perl core live in various subdirectories, where -two are dedicated to core-only modules, and two are for the dual-life modules -which live on CPAN and may be maintained separately with respect to the Perl -core: +However, if you're not using git, you can still produce a suitable +patch. You'll need a pristine copy of the Perl source to diff against. +The porters prefer unified diffs. Using GNU C<diff>, you can produce a +diff like this: - lib/ is for pure-Perl modules, which exist in the core only. + % diff -Npurd perl.pristine perl.mine - ext/ is for XS extensions, and modules with special Makefile.PL - requirements, which exist in the core only. +Make sure that you C<make realclean> in your copy of Perl to remove any +build artifacts, or you may get a confusing result. - cpan/ is for dual-life modules, where the CPAN module is - canonical (should be patched first). +=head3 Commit message - dist/ is for dual-life modules, where the blead source is - canonical. +As you craft each patch you intend to submit to the Perl core, it's +important to write a good commit message. This is especially important +if your submission will consist of a series of commits. -For some dual-life modules it has not been discussed if the CPAN version or the -blead source is canonical. Until that is done, those modules should be in -F<cpan/>. +The first line of the commit message should be a short description +without a period. It should be no longer than the subject line of an +email, 50 characters being a good rule of thumb. -=item Tests +A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will +only display the first line (cut off at 50 characters) when presenting +commit summaries. -There are tests for nearly all the modules, built-ins and major bits -of functionality. Test files all have a .t suffix. Module tests live -in the F<lib/> and F<ext/> directories next to the module being -tested. Others live in F<t/>. See L<Writing a test> +The commit message should include a description of the problem that the +patch corrects or new functionality that the patch adds. -=item Documentation +As a general rule of thumb, your commit message should help a +programmer who knows the Perl core quickly understand what you were +trying to do, how you were trying to do it, and why the change matters +to Perl. -Documentation maintenance includes looking after everything in the -F<pod/> directory, (as well as contributing new documentation) and -the documentation to the modules in core. +=over 4 -=item Configure +=item * Why -The Configure process is the way we make Perl portable across the -myriad of operating systems it supports. Responsibility for the -Configure, build and installation process, as well as the overall -portability of the core code rests with the Configure pumpkin - -others help out with individual operating systems. +Your commit message should describe why the change you are making is +important. When someone looks at your change in six months or six +years, your intent should be clear. -The three files that fall under his/her responsibility are Configure, -config_h.SH, and Porting/Glossary (and a whole bunch of small related -files that are less important here). The Configure pumpkin decides how -patches to these are dealt with. Currently, the Configure pumpkin will -accept patches in most common formats, even directly to these files. -Other committers are allowed to commit to these files under the strict -condition that they will inform the Configure pumpkin, either on IRC -(if he/she happens to be around) or through (personal) e-mail. +If you're deprecating a feature with the intent of later simplifying +another bit of code, say so. If you're fixing a performance problem or +adding a new feature to support some other bit of the core, mention +that. -The files involved are the operating system directories, (F<win32/>, -F<os2/>, F<vms/> and so on) the shell scripts which generate F<config.h> -and F<Makefile>, as well as the metaconfig files which generate -F<Configure>. (metaconfig isn't included in the core distribution.) +=item * What -See http://perl5.git.perl.org/metaconfig.git/blob/HEAD:/README for a -description of the full process involved. +Your commit message should describe what part of the Perl core you're +changing and what you expect your patch to do. -=item Interpreter +=item * How -And of course, there's the core of the Perl interpreter itself. Let's -have a look at that in a little more detail. +While it's not necessary for documentation changes, new tests or +trivial patches, it's often worth explaining how your change works. +Even if it's clear to you today, it may not be clear to a porter next +month or next year. =back -Before we leave looking at the layout, though, don't forget that -F<MANIFEST> contains not only the file names in the Perl distribution, -but short descriptions of what's in them, too. For an overview of the -important files, try this: - - perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST - -=head2 Elements of the interpreter - -The work of the interpreter has two main stages: compiling the code -into the internal representation, or bytecode, and then executing it. -L<perlguts/Compiled code> explains exactly how the compilation stage -happens. +A commit message isn't intended to take the place of comments in your +code. Commit messages should describe the change you made, while code +comments should describe the current state of the code. -Here is a short breakdown of perl's operation: - -=over 3 +If you've just implemented a new feature, complete with doc, tests and +well-commented code, a brief commit message will often suffice. If, +however, you've just changed a single character deep in the parser or +lexer, you might need to write a small novel to ensure that future +readers understand what you did and why you did it. -=item Startup +=head3 Comments, Comments, Comments -The action begins in F<perlmain.c>. (or F<miniperlmain.c> for miniperl) -This is very high-level code, enough to fit on a single screen, and it -resembles the code found in L<perlembed>; most of the real action takes -place in F<perl.c> +Be sure to adequately comment your code. While commenting every line is +unnecessary, anything that takes advantage of side effects of +operators, that creates changes that will be felt outside of the +function being patched, or that others may find confusing should be +documented. If you are going to err, it is better to err on the side of +adding too many comments than too few. -F<perlmain.c> is generated by L<writemain> from F<miniperlmain.c> at -make time, so you should make perl to follow this along. +The best comments explain I<why> the code does what it does, not I<what +it does>. -First, F<perlmain.c> allocates some memory and constructs a Perl -interpreter, along these lines: +=head3 Style - 1 PERL_SYS_INIT3(&argc,&argv,&env); - 2 - 3 if (!PL_do_undump) { - 4 my_perl = perl_alloc(); - 5 if (!my_perl) - 6 exit(1); - 7 perl_construct(my_perl); - 8 PL_perl_destruct_level = 0; - 9 } +In general, please follow the particular style of the code you are +patching. -Line 1 is a macro, and its definition is dependent on your operating -system. Line 3 references C<PL_do_undump>, a global variable - all -global variables in Perl start with C<PL_>. This tells you whether the -current running program was created with the C<-u> flag to perl and then -F<undump>, which means it's going to be false in any sane context. - -Line 4 calls a function in F<perl.c> to allocate memory for a Perl -interpreter. It's quite a simple function, and the guts of it looks like -this: - - my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter)); - -Here you see an example of Perl's system abstraction, which we'll see -later: C<PerlMem_malloc> is either your system's C<malloc>, or Perl's -own C<malloc> as defined in F<malloc.c> if you selected that option at -configure time. - -Next, in line 7, we construct the interpreter using perl_construct, -also in F<perl.c>; this sets up all the special variables that Perl -needs, the stacks, and so on. - -Now we pass Perl the command line options, and tell it to go: - - exitstatus = perl_parse(my_perl, xs_init, argc, argv, (char **)NULL); - if (!exitstatus) - perl_run(my_perl); - - exitstatus = perl_destruct(my_perl); - - perl_free(my_perl); - -C<perl_parse> is actually a wrapper around C<S_parse_body>, as defined -in F<perl.c>, which processes the command line options, sets up any -statically linked XS modules, opens the program and calls C<yyparse> to -parse it. - -=item Parsing - -The aim of this stage is to take the Perl source, and turn it into an op -tree. We'll see what one of those looks like later. Strictly speaking, -there's three things going on here. - -C<yyparse>, the parser, lives in F<perly.c>, although you're better off -reading the original YACC input in F<perly.y>. (Yes, Virginia, there -B<is> a YACC grammar for Perl!) The job of the parser is to take your -code and "understand" it, splitting it into sentences, deciding which -operands go with which operators and so on. - -The parser is nobly assisted by the lexer, which chunks up your input -into tokens, and decides what type of thing each token is: a variable -name, an operator, a bareword, a subroutine, a core function, and so on. -The main point of entry to the lexer is C<yylex>, and that and its -associated routines can be found in F<toke.c>. Perl isn't much like -other computer languages; it's highly context sensitive at times, it can -be tricky to work out what sort of token something is, or where a token -ends. As such, there's a lot of interplay between the tokeniser and the -parser, which can get pretty frightening if you're not used to it. - -As the parser understands a Perl program, it builds up a tree of -operations for the interpreter to perform during execution. The routines -which construct and link together the various operations are to be found -in F<op.c>, and will be examined later. - -=item Optimization - -Now the parsing stage is complete, and the finished tree represents -the operations that the Perl interpreter needs to perform to execute our -program. Next, Perl does a dry run over the tree looking for -optimisations: constant expressions such as C<3 + 4> will be computed -now, and the optimizer will also see if any multiple operations can be -replaced with a single one. For instance, to fetch the variable C<$foo>, -instead of grabbing the glob C<*foo> and looking at the scalar -component, the optimizer fiddles the op tree to use a function which -directly looks up the scalar in question. The main optimizer is C<peep> -in F<op.c>, and many ops have their own optimizing functions. - -=item Running - -Now we're finally ready to go: we have compiled Perl byte code, and all -that's left to do is run it. The actual execution is done by the -C<runops_standard> function in F<run.c>; more specifically, it's done by -these three innocent looking lines: - - while ((PL_op = CALL_FPTR(PL_op->op_ppaddr)(aTHX))) { - PERL_ASYNC_CHECK(); - } - -You may be more comfortable with the Perl version of that: - - PERL_ASYNC_CHECK() while $Perl::op = &{$Perl::op->{function}}; - -Well, maybe not. Anyway, each op contains a function pointer, which -stipulates the function which will actually carry out the operation. -This function will return the next op in the sequence - this allows for -things like C<if> which choose the next op dynamically at run time. -The C<PERL_ASYNC_CHECK> makes sure that things like signals interrupt -execution if required. - -The actual functions called are known as PP code, and they're spread -between four files: F<pp_hot.c> contains the "hot" code, which is most -often used and highly optimized, F<pp_sys.c> contains all the -system-specific functions, F<pp_ctl.c> contains the functions which -implement control structures (C<if>, C<while> and the like) and F<pp.c> -contains everything else. These are, if you like, the C code for Perl's -built-in functions and operators. - -Note that each C<pp_> function is expected to return a pointer to the next -op. Calls to perl subs (and eval blocks) are handled within the same -runops loop, and do not consume extra space on the C stack. For example, -C<pp_entersub> and C<pp_entertry> just push a C<CxSUB> or C<CxEVAL> block -struct onto the context stack which contain the address of the op -following the sub call or eval. They then return the first op of that sub -or eval block, and so execution continues of that sub or block. Later, a -C<pp_leavesub> or C<pp_leavetry> op pops the C<CxSUB> or C<CxEVAL>, -retrieves the return op from it, and returns it. - -=item Exception handing - -Perl's exception handing (i.e. C<die> etc.) is built on top of the low-level -C<setjmp()>/C<longjmp()> C-library functions. These basically provide a -way to capture the current PC and SP registers and later restore them; i.e. -a C<longjmp()> continues at the point in code where a previous C<setjmp()> -was done, with anything further up on the C stack being lost. This is why -code should always save values using C<SAVE_FOO> rather than in auto -variables. - -The perl core wraps C<setjmp()> etc in the macros C<JMPENV_PUSH> and -C<JMPENV_JUMP>. The basic rule of perl exceptions is that C<exit>, and -C<die> (in the absence of C<eval>) perform a C<JMPENV_JUMP(2)>, while -C<die> within C<eval> does a C<JMPENV_JUMP(3)>. - -At entry points to perl, such as C<perl_parse()>, C<perl_run()> and -C<call_sv(cv, G_EVAL)> each does a C<JMPENV_PUSH>, then enter a runops -loop or whatever, and handle possible exception returns. For a 2 return, -final cleanup is performed, such as popping stacks and calling C<CHECK> or -C<END> blocks. Amongst other things, this is how scope cleanup still -occurs during an C<exit>. - -If a C<die> can find a C<CxEVAL> block on the context stack, then the -stack is popped to that level and the return op in that block is assigned -to C<PL_restartop>; then a C<JMPENV_JUMP(3)> is performed. This normally -passes control back to the guard. In the case of C<perl_run> and -C<call_sv>, a non-null C<PL_restartop> triggers re-entry to the runops -loop. The is the normal way that C<die> or C<croak> is handled within an -C<eval>. - -Sometimes ops are executed within an inner runops loop, such as tie, sort -or overload code. In this case, something like - - sub FETCH { eval { die } } - -would cause a longjmp right back to the guard in C<perl_run>, popping both -runops loops, which is clearly incorrect. One way to avoid this is for the -tie code to do a C<JMPENV_PUSH> before executing C<FETCH> in the inner -runops loop, but for efficiency reasons, perl in fact just sets a flag, -using C<CATCH_SET(TRUE)>. The C<pp_require>, C<pp_entereval> and -C<pp_entertry> ops check this flag, and if true, they call C<docatch>, -which does a C<JMPENV_PUSH> and starts a new runops level to execute the -code, rather than doing it on the current loop. - -As a further optimisation, on exit from the eval block in the C<FETCH>, -execution of the code following the block is still carried on in the inner -loop. When an exception is raised, C<docatch> compares the C<JMPENV> -level of the C<CxEVAL> with C<PL_top_env> and if they differ, just -re-throws the exception. In this way any inner loops get popped. - -Here's an example. - - 1: eval { tie @a, 'A' }; - 2: sub A::TIEARRAY { - 3: eval { die }; - 4: die; - 5: } - -To run this code, C<perl_run> is called, which does a C<JMPENV_PUSH> then -enters a runops loop. This loop executes the eval and tie ops on line 1, -with the eval pushing a C<CxEVAL> onto the context stack. - -The C<pp_tie> does a C<CATCH_SET(TRUE)>, then starts a second runops loop -to execute the body of C<TIEARRAY>. When it executes the entertry op on -line 3, C<CATCH_GET> is true, so C<pp_entertry> calls C<docatch> which -does a C<JMPENV_PUSH> and starts a third runops loop, which then executes -the die op. At this point the C call stack looks like this: - - Perl_pp_die - Perl_runops # third loop - S_docatch_body - S_docatch - Perl_pp_entertry - Perl_runops # second loop - S_call_body - Perl_call_sv - Perl_pp_tie - Perl_runops # first loop - S_run_body - perl_run - main - -and the context and data stacks, as shown by C<-Dstv>, look like: - - STACK 0: MAIN - CX 0: BLOCK => - CX 1: EVAL => AV() PV("A"\0) - retop=leave - STACK 1: MAGIC - CX 0: SUB => - retop=(null) - CX 1: EVAL => * - retop=nextstate - -The die pops the first C<CxEVAL> off the context stack, sets -C<PL_restartop> from it, does a C<JMPENV_JUMP(3)>, and control returns to -the top C<docatch>. This then starts another third-level runops level, -which executes the nextstate, pushmark and die ops on line 4. At the point -that the second C<pp_die> is called, the C call stack looks exactly like -that above, even though we are no longer within an inner eval; this is -because of the optimization mentioned earlier. However, the context stack -now looks like this, ie with the top CxEVAL popped: - - STACK 0: MAIN - CX 0: BLOCK => - CX 1: EVAL => AV() PV("A"\0) - retop=leave - STACK 1: MAGIC - CX 0: SUB => - retop=(null) - -The die on line 4 pops the context stack back down to the CxEVAL, leaving -it as: - - STACK 0: MAIN - CX 0: BLOCK => - -As usual, C<PL_restartop> is extracted from the C<CxEVAL>, and a -C<JMPENV_JUMP(3)> done, which pops the C stack back to the docatch: - - S_docatch - Perl_pp_entertry - Perl_runops # second loop - S_call_body - Perl_call_sv - Perl_pp_tie - Perl_runops # first loop - S_run_body - perl_run - main - -In this case, because the C<JMPENV> level recorded in the C<CxEVAL> -differs from the current one, C<docatch> just does a C<JMPENV_JUMP(3)> -and the C stack unwinds to: - - perl_run - main - -Because C<PL_restartop> is non-null, C<run_body> starts a new runops loop -and execution continues. +In particular, follow these general guidelines for patching Perl +sources: -=back - -=head2 Internal Variable Types - -You should by now have had a look at L<perlguts>, which tells you about -Perl's internal variable types: SVs, HVs, AVs and the rest. If not, do -that now. - -These variables are used not only to represent Perl-space variables, but -also any constants in the code, as well as some structures completely -internal to Perl. The symbol table, for instance, is an ordinary Perl -hash. Your code is represented by an SV as it's read into the parser; -any program files you call are opened via ordinary Perl filehandles, and -so on. - -The core L<Devel::Peek|Devel::Peek> module lets us examine SVs from a -Perl program. Let's see, for instance, how Perl treats the constant -C<"hello">. - - % perl -MDevel::Peek -e 'Dump("hello")' - 1 SV = PV(0xa041450) at 0xa04ecbc - 2 REFCNT = 1 - 3 FLAGS = (POK,READONLY,pPOK) - 4 PV = 0xa0484e0 "hello"\0 - 5 CUR = 5 - 6 LEN = 6 - -Reading C<Devel::Peek> output takes a bit of practise, so let's go -through it line by line. - -Line 1 tells us we're looking at an SV which lives at C<0xa04ecbc> in -memory. SVs themselves are very simple structures, but they contain a -pointer to a more complex structure. In this case, it's a PV, a -structure which holds a string value, at location C<0xa041450>. Line 2 -is the reference count; there are no other references to this data, so -it's 1. - -Line 3 are the flags for this SV - it's OK to use it as a PV, it's a -read-only SV (because it's a constant) and the data is a PV internally. -Next we've got the contents of the string, starting at location -C<0xa0484e0>. - -Line 5 gives us the current length of the string - note that this does -B<not> include the null terminator. Line 6 is not the length of the -string, but the length of the currently allocated buffer; as the string -grows, Perl automatically extends the available storage via a routine -called C<SvGROW>. - -You can get at any of these quantities from C very easily; just add -C<Sv> to the name of the field shown in the snippet, and you've got a -macro which will return the value: C<SvCUR(sv)> returns the current -length of the string, C<SvREFCOUNT(sv)> returns the reference count, -C<SvPV(sv, len)> returns the string itself with its length, and so on. -More macros to manipulate these properties can be found in L<perlguts>. - -Let's take an example of manipulating a PV, from C<sv_catpvn>, in F<sv.c> - - 1 void - 2 Perl_sv_catpvn(pTHX_ register SV *sv, register const char *ptr, register STRLEN len) - 3 { - 4 STRLEN tlen; - 5 char *junk; - - 6 junk = SvPV_force(sv, tlen); - 7 SvGROW(sv, tlen + len + 1); - 8 if (ptr == junk) - 9 ptr = SvPVX(sv); - 10 Move(ptr,SvPVX(sv)+tlen,len,char); - 11 SvCUR(sv) += len; - 12 *SvEND(sv) = '\0'; - 13 (void)SvPOK_only_UTF8(sv); /* validate pointer */ - 14 SvTAINT(sv); - 15 } - -This is a function which adds a string, C<ptr>, of length C<len> onto -the end of the PV stored in C<sv>. The first thing we do in line 6 is -make sure that the SV B<has> a valid PV, by calling the C<SvPV_force> -macro to force a PV. As a side effect, C<tlen> gets set to the current -value of the PV, and the PV itself is returned to C<junk>. - -In line 7, we make sure that the SV will have enough room to accommodate -the old string, the new string and the null terminator. If C<LEN> isn't -big enough, C<SvGROW> will reallocate space for us. - -Now, if C<junk> is the same as the string we're trying to add, we can -grab the string directly from the SV; C<SvPVX> is the address of the PV -in the SV. - -Line 10 does the actual catenation: the C<Move> macro moves a chunk of -memory around: we move the string C<ptr> to the end of the PV - that's -the start of the PV plus its current length. We're moving C<len> bytes -of type C<char>. After doing so, we need to tell Perl we've extended the -string, by altering C<CUR> to reflect the new length. C<SvEND> is a -macro which gives us the end of the string, so that needs to be a -C<"\0">. - -Line 13 manipulates the flags; since we've changed the PV, any IV or NV -values will no longer be valid: if we have C<$a=10; $a.="6";> we don't -want to use the old IV of 10. C<SvPOK_only_utf8> is a special UTF-8-aware -version of C<SvPOK_only>, a macro which turns off the IOK and NOK flags -and turns on POK. The final C<SvTAINT> is a macro which launders tainted -data if taint mode is turned on. - -AVs and HVs are more complicated, but SVs are by far the most common -variable type being thrown around. Having seen something of how we -manipulate these, let's go on and look at how the op tree is -constructed. - -=head2 Op Trees - -First, what is the op tree, anyway? The op tree is the parsed -representation of your program, as we saw in our section on parsing, and -it's the sequence of operations that Perl goes through to execute your -program, as we saw in L</Running>. - -An op is a fundamental operation that Perl can perform: all the built-in -functions and operators are ops, and there are a series of ops which -deal with concepts the interpreter needs internally - entering and -leaving a block, ending a statement, fetching a variable, and so on. - -The op tree is connected in two ways: you can imagine that there are two -"routes" through it, two orders in which you can traverse the tree. -First, parse order reflects how the parser understood the code, and -secondly, execution order tells perl what order to perform the -operations in. - -The easiest way to examine the op tree is to stop Perl after it has -finished parsing, and get it to dump out the tree. This is exactly what -the compiler backends L<B::Terse|B::Terse>, L<B::Concise|B::Concise> -and L<B::Debug|B::Debug> do. - -Let's have a look at how Perl sees C<$a = $b + $c>: - - % perl -MO=Terse -e '$a=$b+$c' - 1 LISTOP (0x8179888) leave - 2 OP (0x81798b0) enter - 3 COP (0x8179850) nextstate - 4 BINOP (0x8179828) sassign - 5 BINOP (0x8179800) add [1] - 6 UNOP (0x81796e0) null [15] - 7 SVOP (0x80fafe0) gvsv GV (0x80fa4cc) *b - 8 UNOP (0x81797e0) null [15] - 9 SVOP (0x8179700) gvsv GV (0x80efeb0) *c - 10 UNOP (0x816b4f0) null [15] - 11 SVOP (0x816dcf0) gvsv GV (0x80fa460) *a - -Let's start in the middle, at line 4. This is a BINOP, a binary -operator, which is at location C<0x8179828>. The specific operator in -question is C<sassign> - scalar assignment - and you can find the code -which implements it in the function C<pp_sassign> in F<pp_hot.c>. As a -binary operator, it has two children: the add operator, providing the -result of C<$b+$c>, is uppermost on line 5, and the left hand side is on -line 10. - -Line 10 is the null op: this does exactly nothing. What is that doing -there? If you see the null op, it's a sign that something has been -optimized away after parsing. As we mentioned in L</Optimization>, -the optimization stage sometimes converts two operations into one, for -example when fetching a scalar variable. When this happens, instead of -rewriting the op tree and cleaning up the dangling pointers, it's easier -just to replace the redundant operation with the null op. Originally, -the tree would have looked like this: - - 10 SVOP (0x816b4f0) rv2sv [15] - 11 SVOP (0x816dcf0) gv GV (0x80fa460) *a - -That is, fetch the C<a> entry from the main symbol table, and then look -at the scalar component of it: C<gvsv> (C<pp_gvsv> into F<pp_hot.c>) -happens to do both these things. - -The right hand side, starting at line 5 is similar to what we've just -seen: we have the C<add> op (C<pp_add> also in F<pp_hot.c>) add together -two C<gvsv>s. - -Now, what's this about? - - 1 LISTOP (0x8179888) leave - 2 OP (0x81798b0) enter - 3 COP (0x8179850) nextstate - -C<enter> and C<leave> are scoping ops, and their job is to perform any -housekeeping every time you enter and leave a block: lexical variables -are tidied up, unreferenced variables are destroyed, and so on. Every -program will have those first three lines: C<leave> is a list, and its -children are all the statements in the block. Statements are delimited -by C<nextstate>, so a block is a collection of C<nextstate> ops, with -the ops to be performed for each statement being the children of -C<nextstate>. C<enter> is a single op which functions as a marker. - -That's how Perl parsed the program, from top to bottom: - - Program - | - Statement - | - = - / \ - / \ - $a + - / \ - $b $c - -However, it's impossible to B<perform> the operations in this order: -you have to find the values of C<$b> and C<$c> before you add them -together, for instance. So, the other thread that runs through the op -tree is the execution order: each op has a field C<op_next> which points -to the next op to be run, so following these pointers tells us how perl -executes the code. We can traverse the tree in this order using -the C<exec> option to C<B::Terse>: - - % perl -MO=Terse,exec -e '$a=$b+$c' - 1 OP (0x8179928) enter - 2 COP (0x81798c8) nextstate - 3 SVOP (0x81796c8) gvsv GV (0x80fa4d4) *b - 4 SVOP (0x8179798) gvsv GV (0x80efeb0) *c - 5 BINOP (0x8179878) add [1] - 6 SVOP (0x816dd38) gvsv GV (0x80fa468) *a - 7 BINOP (0x81798a0) sassign - 8 LISTOP (0x8179900) leave - -This probably makes more sense for a human: enter a block, start a -statement. Get the values of C<$b> and C<$c>, and add them together. -Find C<$a>, and assign one to the other. Then leave. - -The way Perl builds up these op trees in the parsing process can be -unravelled by examining F<perly.y>, the YACC grammar. Let's take the -piece we need to construct the tree for C<$a = $b + $c> - - 1 term : term ASSIGNOP term - 2 { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); } - 3 | term ADDOP term - 4 { $$ = newBINOP($2, 0, scalar($1), scalar($3)); } - -If you're not used to reading BNF grammars, this is how it works: You're -fed certain things by the tokeniser, which generally end up in upper -case. Here, C<ADDOP>, is provided when the tokeniser sees C<+> in your -code. C<ASSIGNOP> is provided when C<=> is used for assigning. These are -"terminal symbols", because you can't get any simpler than them. - -The grammar, lines one and three of the snippet above, tells you how to -build up more complex forms. These complex forms, "non-terminal symbols" -are generally placed in lower case. C<term> here is a non-terminal -symbol, representing a single expression. - -The grammar gives you the following rule: you can make the thing on the -left of the colon if you see all the things on the right in sequence. -This is called a "reduction", and the aim of parsing is to completely -reduce the input. There are several different ways you can perform a -reduction, separated by vertical bars: so, C<term> followed by C<=> -followed by C<term> makes a C<term>, and C<term> followed by C<+> -followed by C<term> can also make a C<term>. - -So, if you see two terms with an C<=> or C<+>, between them, you can -turn them into a single expression. When you do this, you execute the -code in the block on the next line: if you see C<=>, you'll do the code -in line 2. If you see C<+>, you'll do the code in line 4. It's this code -which contributes to the op tree. - - | term ADDOP term - { $$ = newBINOP($2, 0, scalar($1), scalar($3)); } - -What this does is creates a new binary op, and feeds it a number of -variables. The variables refer to the tokens: C<$1> is the first token in -the input, C<$2> the second, and so on - think regular expression -backreferences. C<$$> is the op returned from this reduction. So, we -call C<newBINOP> to create a new binary operator. The first parameter to -C<newBINOP>, a function in F<op.c>, is the op type. It's an addition -operator, so we want the type to be C<ADDOP>. We could specify this -directly, but it's right there as the second token in the input, so we -use C<$2>. The second parameter is the op's flags: 0 means "nothing -special". Then the things to add: the left and right hand side of our -expression, in scalar context. - -=head2 Stacks - -When perl executes something like C<addop>, how does it pass on its -results to the next op? The answer is, through the use of stacks. Perl -has a number of stacks to store things it's currently working on, and -we'll look at the three most important ones here. - -=over 3 - -=item Argument stack - -Arguments are passed to PP code and returned from PP code using the -argument stack, C<ST>. The typical way to handle arguments is to pop -them off the stack, deal with them how you wish, and then push the result -back onto the stack. This is how, for instance, the cosine operator -works: - - NV value; - value = POPn; - value = Perl_cos(value); - XPUSHn(value); - -We'll see a more tricky example of this when we consider Perl's macros -below. C<POPn> gives you the NV (floating point value) of the top SV on -the stack: the C<$x> in C<cos($x)>. Then we compute the cosine, and push -the result back as an NV. The C<X> in C<XPUSHn> means that the stack -should be extended if necessary - it can't be necessary here, because we -know there's room for one more item on the stack, since we've just -removed one! The C<XPUSH*> macros at least guarantee safety. - -Alternatively, you can fiddle with the stack directly: C<SP> gives you -the first element in your portion of the stack, and C<TOP*> gives you -the top SV/IV/NV/etc. on the stack. So, for instance, to do unary -negation of an integer: - - SETi(-TOPi); - -Just set the integer value of the top stack entry to its negation. - -Argument stack manipulation in the core is exactly the same as it is in -XSUBs - see L<perlxstut>, L<perlxs> and L<perlguts> for a longer -description of the macros used in stack manipulation. - -=item Mark stack - -I say "your portion of the stack" above because PP code doesn't -necessarily get the whole stack to itself: if your function calls -another function, you'll only want to expose the arguments aimed for the -called function, and not (necessarily) let it get at your own data. The -way we do this is to have a "virtual" bottom-of-stack, exposed to each -function. The mark stack keeps bookmarks to locations in the argument -stack usable by each function. For instance, when dealing with a tied -variable, (internally, something with "P" magic) Perl has to call -methods for accesses to the tied variables. However, we need to separate -the arguments exposed to the method to the argument exposed to the -original function - the store or fetch or whatever it may be. Here's -roughly how the tied C<push> is implemented; see C<av_push> in F<av.c>: - - 1 PUSHMARK(SP); - 2 EXTEND(SP,2); - 3 PUSHs(SvTIED_obj((SV*)av, mg)); - 4 PUSHs(val); - 5 PUTBACK; - 6 ENTER; - 7 call_method("PUSH", G_SCALAR|G_DISCARD); - 8 LEAVE; - -Let's examine the whole implementation, for practice: - - 1 PUSHMARK(SP); - -Push the current state of the stack pointer onto the mark stack. This is -so that when we've finished adding items to the argument stack, Perl -knows how many things we've added recently. - - 2 EXTEND(SP,2); - 3 PUSHs(SvTIED_obj((SV*)av, mg)); - 4 PUSHs(val); - -We're going to add two more items onto the argument stack: when you have -a tied array, the C<PUSH> subroutine receives the object and the value -to be pushed, and that's exactly what we have here - the tied object, -retrieved with C<SvTIED_obj>, and the value, the SV C<val>. - - 5 PUTBACK; - -Next we tell Perl to update the global stack pointer from our internal -variable: C<dSP> only gave us a local copy, not a reference to the global. - - 6 ENTER; - 7 call_method("PUSH", G_SCALAR|G_DISCARD); - 8 LEAVE; - -C<ENTER> and C<LEAVE> localise a block of code - they make sure that all -variables are tidied up, everything that has been localised gets -its previous value returned, and so on. Think of them as the C<{> and -C<}> of a Perl block. - -To actually do the magic method call, we have to call a subroutine in -Perl space: C<call_method> takes care of that, and it's described in -L<perlcall>. We call the C<PUSH> method in scalar context, and we're -going to discard its return value. The call_method() function -removes the top element of the mark stack, so there is nothing for -the caller to clean up. - -=item Save stack - -C doesn't have a concept of local scope, so perl provides one. We've -seen that C<ENTER> and C<LEAVE> are used as scoping braces; the save -stack implements the C equivalent of, for example: - - { - local $foo = 42; - ... - } - -See L<perlguts/Localising Changes> for how to use the save stack. - -=back +=over 4 -=head2 Millions of Macros +=item * -One thing you'll notice about the Perl source is that it's full of -macros. Some have called the pervasive use of macros the hardest thing -to understand, others find it adds to clarity. Let's take an example, -the code which implements the addition operator: +8-wide tabs (no exceptions!) - 1 PP(pp_add) - 2 { - 3 dSP; dATARGET; tryAMAGICbin(add,opASSIGN); - 4 { - 5 dPOPTOPnnrl_ul; - 6 SETn( left + right ); - 7 RETURN; - 8 } - 9 } +=item * -Every line here (apart from the braces, of course) contains a macro. The -first line sets up the function declaration as Perl expects for PP code; -line 3 sets up variable declarations for the argument stack and the -target, the return value of the operation. Finally, it tries to see if -the addition operation is overloaded; if so, the appropriate subroutine -is called. +4-wide indents for code, 2-wide indents for nested CPP #defines -Line 5 is another variable declaration - all variable declarations start -with C<d> - which pops from the top of the argument stack two NVs (hence -C<nn>) and puts them into the variables C<right> and C<left>, hence the -C<rl>. These are the two operands to the addition operator. Next, we -call C<SETn> to set the NV of the return value to the result of adding -the two values. This done, we return - the C<RETURN> macro makes sure -that our return value is properly handled, and we pass the next operator -to run back to the main run loop. +=item * -Most of these macros are explained in L<perlapi>, and some of the more -important ones are explained in L<perlxs> as well. Pay special attention -to L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for information on -the C<[pad]THX_?> macros. +Try hard not to exceed 79-columns -=head2 The .i Targets +=item * -You can expand the macros in a F<foo.c> file by saying +ANSI C prototypes - make foo.i +=item * -which will expand the macros using cpp. Don't be scared by the results. +Uncuddled elses and "K&R" style for indenting control constructs -=head1 SOURCE CODE STATIC ANALYSIS +=item * -Various tools exist for analysing C source code B<statically>, as -opposed to B<dynamically>, that is, without executing the code. -It is possible to detect resource leaks, undefined behaviour, type -mismatches, portability problems, code paths that would cause illegal -memory accesses, and other similar problems by just parsing the C code -and looking at the resulting graph, what does it tell about the -execution and data flows. As a matter of fact, this is exactly -how C compilers know to give warnings about dubious code. +No C++ style (//) comments -=head2 lint, splint +=item * -The good old C code quality inspector, C<lint>, is available in -several platforms, but please be aware that there are several -different implementations of it by different vendors, which means that -the flags are not identical across different platforms. +Mark places that need to be revisited with XXX (and revisit often!) -There is a lint variant called C<splint> (Secure Programming Lint) -available from http://www.splint.org/ that should compile on any -Unix-like platform. +=item * -There are C<lint> and <splint> targets in Makefile, but you may have -to diddle with the flags (see above). +Opening brace lines up with "if" when conditional spans multiple lines; +should be at end-of-line otherwise -=head2 Coverity +=item * -Coverity (http://www.coverity.com/) is a product similar to lint and -as a testbed for their product they periodically check several open -source projects, and they give out accounts to open source developers -to the defect databases. +In function definitions, name starts in column 0 (return value is on +previous line) -=head2 cpd (cut-and-paste detector) +=item * -The cpd tool detects cut-and-paste coding. If one instance of the -cut-and-pasted code changes, all the other spots should probably be -changed, too. Therefore such code should probably be turned into a -subroutine or a macro. +Single space after keywords that are followed by parens, no space +between function name and following paren -cpd (http://pmd.sourceforge.net/cpd.html) is part of the pmd project -(http://pmd.sourceforge.net/). pmd was originally written for static -analysis of Java code, but later the cpd part of it was extended to -parse also C and C++. +=item * -Download the pmd-bin-X.Y.zip () from the SourceForge site, extract the -pmd-X.Y.jar from it, and then run that on source code thusly: +Avoid assignments in conditionals, but if they're unavoidable, use +extra paren, e.g. "if (a && (b = c)) ..." - java -cp pmd-X.Y.jar net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /some/where/src --language c > cpd.txt +=item * -You may run into memory limits, in which case you should use the -Xmx option: +"return foo;" rather than "return(foo);" - java -Xmx512M ... +=item * -=head2 gcc warnings +"if (!foo) ..." rather than "if (foo == FALSE) ..." etc. -Though much can be written about the inconsistency and coverage -problems of gcc warnings (like C<-Wall> not meaning "all the -warnings", or some common portability problems not being covered by -C<-Wall>, or C<-ansi> and C<-pedantic> both being a poorly defined -collection of warnings, and so forth), gcc is still a useful tool in -keeping our coding nose clean. +=back -The C<-Wall> is by default on. +=head3 Test suite -The C<-ansi> (and its sidekick, C<-pedantic>) would be nice to be on -always, but unfortunately they are not safe on all platforms, they can -for example cause fatal conflicts with the system headers (Solaris -being a prime example). If Configure C<-Dgccansipedantic> is used, -the C<cflags> frontend selects C<-ansi -pedantic> for the platforms -where they are known to be safe. +If your patch changes code (rather than just changing documentation), +you should also include one or more test cases which illustrate the bug +you're fixing or validate the new functionality you're adding. In +general, you should update an existing test file rather than create a +new one. -Starting from Perl 5.9.4 the following extra flags are added: +Your test suite additions should generally follow these guidelines +(courtesy of Gurusamy Sarathy <gsar@activestate.com>): =over 4 =item * -C<-Wendif-labels> +Know what you're testing. Read the docs, and the source. =item * -C<-Wextra> +Tend to fail, not succeed. =item * -C<-Wdeclaration-after-statement> - -=back - -The following flags would be nice to have but they would first need -their own Augean stablemaster: - -=over 4 +Interpret results strictly. =item * -C<-Wpointer-arith> +Use unrelated features (this will flush out bizarre interactions). =item * -C<-Wshadow> +Use non-standard idioms (otherwise you are not testing TIMTOWTDI). =item * -C<-Wstrict-prototypes> - -=back +Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT +found in t/op/tie.t is much more maintainable, and gives better failure +reports). -The C<-Wtraditional> is another example of the annoying tendency of -gcc to bundle a lot of warnings under one switch (it would be -impossible to deploy in practice because it would complain a lot) but -it does contain some warnings that would be beneficial to have available -on their own, such as the warning about string constants inside macros -containing the macro arguments: this behaved differently pre-ANSI -than it does in ANSI, and some C compilers are still in transition, -AIX being an example. - -=head2 Warnings of other C compilers - -Other C compilers (yes, there B<are> other C compilers than gcc) often -have their "strict ANSI" or "strict ANSI with some portability extensions" -modes on, like for example the Sun Workshop has its C<-Xa> mode on -(though implicitly), or the DEC (these days, HP...) has its C<-std1> -mode on. +=item * -=head2 DEBUGGING +Give meaningful error messages when a test fails. -You can compile a special debugging version of Perl, which allows you -to use the C<-D> option of Perl to tell more about what Perl is doing. -But sometimes there is no alternative than to dive in with a debugger, -either to see the stack trace of a core dump (very useful in a bug -report), or trying to figure out what went wrong before the core dump -happened, or how did we end up having wrong or unexpected results. +=item * -=head2 Poking at Perl +Avoid using qx// and system() unless you are testing for them. If you +do use them, make sure that you cover _all_ perl platforms. -To really poke around with Perl, you'll probably want to build Perl for -debugging, like this: +=item * - ./Configure -d -D optimize=-g - make +Unlink any temporary files you create. -C<-g> is a flag to the C compiler to have it produce debugging -information which will allow us to step through a running program, -and to see in which C function we are at (without the debugging -information we might see only the numerical addresses of the functions, -which is not very helpful). +=item * -F<Configure> will also turn on the C<DEBUGGING> compilation symbol which -enables all the internal debugging code in Perl. There are a whole bunch -of things you can debug with this: L<perlrun> lists them all, and the -best way to find out about them is to play about with them. The most -useful options are probably +Promote unforeseen warnings to errors with $SIG{__WARN__}. - l Context (loop) stack processing - t Trace execution - o Method and overloading resolution - c String/numeric conversions +=item * -Some of the functionality of the debugging code can be achieved using XS -modules. +Be sure to use the libraries and modules shipped with the version being +tested, not those that were already installed. - -Dr => use re 'debug' - -Dx => use O 'Debug' +=item * -=head2 Using a source-level debugger +Add comments to the code explaining what you are testing for. -If the debugging output of C<-D> doesn't help you, it's time to step -through perl's execution with a source-level debugger. +=item * -=over 3 +Make updating the '1..42' string unnecessary. Or make sure that you +update it. =item * -We'll use C<gdb> for our examples here; the principles will apply to -any debugger (many vendors call their debugger C<dbx>), but check the -manual of the one you're using. +Test _all_ behaviors of a given operator, library, or function. -=back +Test all optional arguments. -To fire up the debugger, type +Test return values in various contexts (boolean, scalar, list, lvalue). - gdb ./perl +Use both global and lexical variables. -Or if you have a core dump: +Don't forget the exceptional, pathological cases. - gdb ./perl core +=back -You'll want to do that in your Perl source tree so the debugger can read -the source code. You should see the copyright message, followed by the -prompt. +=head2 Patching a core module - (gdb) +This works just like patching anything else, with one extra +consideration. -C<help> will get you into the documentation, but here are the most -useful commands: +Some core modules also live on CPAN and are maintained outside of the +Perl core. When the author updates the module, the updates are simply +copied into the core. -=over 3 +Modules in the F<cpan/> directory of the source tree are maintained +outside of the Perl core. See that module's listing on documentation or +its listing on L<http://search.cpan.org/> for more information on +reporting bugs and submitting patches. -=item run [args] +In contrast, modules in the F<dist/> directory are maintained in the +core. -Run the program with the given arguments. +=head2 Updating perldelta -=item break function_name +For changes significant enough to warrant a F<pod/perldelta.pod> entry, +the porters will greatly appreciate it if you submit a delta entry +along with your actual change. Significant changes include, but are not +limited to: -=item break source.c:xxx +=over 4 -Tells the debugger that we'll want to pause execution when we reach -either the named function (but see L<perlguts/Internal Functions>!) or the given -line in the named source file. +=item * -=item step +Adding, deprecating, or removing core features -Steps through the program a line at a time. +=item * -=item next +Adding, deprecating, removing, or upgrading core or dual-life modules -Steps through the program a line at a time, without descending into -functions. +=item * -=item continue +Adding new core tests -Run until the next breakpoint. +=item * -=item finish +Fixing security issues and user-visible bugs in the core -Run until the end of the current function, then stop again. +=item * -=item 'enter' +Changes that might break existing code, either on the perl or C level -Just pressing Enter will do the most recent operation again - it's a -blessing when stepping through miles of source code. +=item * -=item print +Significant performance improvements -Execute the given C code and print its results. B<WARNING>: Perl makes -heavy use of macros, and F<gdb> does not necessarily support macros -(see later L</"gdb macro support">). You'll have to substitute them -yourself, or to invoke cpp on the source code files -(see L</"The .i Targets">) -So, for instance, you can't say +=item * - print SvPV_nolen(sv) +Adding, removing, or significantly changing documentation in the +F<pod/> directory -but you have to say +=item * - print Perl_sv_2pv_nolen(sv) +Important platform-specific changes =back -You may find it helpful to have a "macro dictionary", which you can -produce by saying C<cpp -dM perl.c | sort>. Even then, F<cpp> won't -recursively apply those macros for you. - -=head2 gdb macro support - -Recent versions of F<gdb> have fairly good macro support, but -in order to use it you'll need to compile perl with macro definitions -included in the debugging information. Using F<gcc> version 3.1, this -means configuring with C<-Doptimize=-g3>. Other compilers might use a -different switch (if they support debugging macros at all). - -=head2 Dumping Perl Data Structures - -One way to get around this macro hell is to use the dumping functions in -F<dump.c>; these work a little like an internal -L<Devel::Peek|Devel::Peek>, but they also cover OPs and other structures -that you can't get at from Perl. Let's take an example. We'll use the -C<$a = $b + $c> we used before, but give it a bit of context: -C<$b = "6XXXX"; $c = 2.3;>. Where's a good place to stop and poke around? - -What about C<pp_add>, the function we examined earlier to implement the -C<+> operator: - - (gdb) break Perl_pp_add - Breakpoint 1 at 0x46249f: file pp_hot.c, line 309. - -Notice we use C<Perl_pp_add> and not C<pp_add> - see L<perlguts/Internal Functions>. -With the breakpoint in place, we can run our program: - - (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c' - -Lots of junk will go past as gdb reads in the relevant source files and -libraries, and then: - - Breakpoint 1, Perl_pp_add () at pp_hot.c:309 - 309 dSP; dATARGET; tryAMAGICbin(add,opASSIGN); - (gdb) step - 311 dPOPTOPnnrl_ul; - (gdb) - -We looked at this bit of code before, and we said that C<dPOPTOPnnrl_ul> -arranges for two C<NV>s to be placed into C<left> and C<right> - let's -slightly expand it: - - #define dPOPTOPnnrl_ul NV right = POPn; \ - SV *leftsv = TOPs; \ - NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0 - -C<POPn> takes the SV from the top of the stack and obtains its NV either -directly (if C<SvNOK> is set) or by calling the C<sv_2nv> function. -C<TOPs> takes the next SV from the top of the stack - yes, C<POPn> uses -C<TOPs> - but doesn't remove it. We then use C<SvNV> to get the NV from -C<leftsv> in the same way as before - yes, C<POPn> uses C<SvNV>. - -Since we don't have an NV for C<$b>, we'll have to use C<sv_2nv> to -convert it. If we step again, we'll find ourselves there: - - Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669 - 1669 if (!sv) - (gdb) - -We can now use C<Perl_sv_dump> to investigate the SV: - - SV = PV(0xa057cc0) at 0xa0675d0 - REFCNT = 1 - FLAGS = (POK,pPOK) - PV = 0xa06a510 "6XXXX"\0 - CUR = 5 - LEN = 6 - $1 = void - -We know we're going to get C<6> from this, so let's finish the -subroutine: - - (gdb) finish - Run till exit from #0 Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671 - 0x462669 in Perl_pp_add () at pp_hot.c:311 - 311 dPOPTOPnnrl_ul; - -We can also dump out this op: the current op is always stored in -C<PL_op>, and we can dump it with C<Perl_op_dump>. This'll give us -similar output to L<B::Debug|B::Debug>. - - { - 13 TYPE = add ===> 14 - TARG = 1 - FLAGS = (SCALAR,KIDS) - { - TYPE = null ===> (12) - (was rv2sv) - FLAGS = (SCALAR,KIDS) - { - 11 TYPE = gvsv ===> 12 - FLAGS = (SCALAR) - GV = main::b - } - } - -# finish this later # - -=head2 Patching - -All right, we've now had a look at how to navigate the Perl sources and -some things you'll need to know when fiddling with them. Let's now get -on and create a simple patch. Here's something Larry suggested: if a -C<U> is the first active format during a C<pack>, (for example, -C<pack "U3C8", @stuff>) then the resulting string should be treated as -UTF-8 encoded. - -If you are working with a git clone of the Perl repository, you will want to -create a branch for your changes. This will make creating a proper patch much -simpler. See the L<perlrepository> for details on how to do this. - -How do we prepare to fix this up? First we locate the code in question - -the C<pack> happens at runtime, so it's going to be in one of the F<pp> -files. Sure enough, C<pp_pack> is in F<pp.c>. Since we're going to be -altering this file, let's copy it to F<pp.c~>. - -[Well, it was in F<pp.c> when this tutorial was written. It has now been -split off with C<pp_unpack> to its own file, F<pp_pack.c>] - -Now let's look over C<pp_pack>: we take a pattern into C<pat>, and then -loop over the pattern, taking each format character in turn into -C<datum_type>. Then for each possible format character, we swallow up -the other arguments in the pattern (a field width, an asterisk, and so -on) and convert the next chunk input into the specified format, adding -it onto the output SV C<cat>. - -How do we know if the C<U> is the first format in the C<pat>? Well, if -we have a pointer to the start of C<pat> then, if we see a C<U> we can -test whether we're still at the start of the string. So, here's where -C<pat> is set up: - - STRLEN fromlen; - register char *pat = SvPVx(*++MARK, fromlen); - register char *patend = pat + fromlen; - register I32 len; - I32 datumtype; - SV *fromstr; - -We'll have another string pointer in there: - - STRLEN fromlen; - register char *pat = SvPVx(*++MARK, fromlen); - register char *patend = pat + fromlen; - + char *patcopy; - register I32 len; - I32 datumtype; - SV *fromstr; - -And just before we start the loop, we'll set C<patcopy> to be the start -of C<pat>: - - items = SP - MARK; - MARK++; - sv_setpvn(cat, "", 0); - + patcopy = pat; - while (pat < patend) { - -Now if we see a C<U> which was at the start of the string, we turn on -the C<UTF8> flag for the output SV, C<cat>: - - + if (datumtype == 'U' && pat==patcopy+1) - + SvUTF8_on(cat); - if (datumtype == '#') { - while (pat < patend && *pat != '\n') - pat++; - -Remember that it has to be C<patcopy+1> because the first character of -the string is the C<U> which has been swallowed into C<datumtype!> - -Oops, we forgot one thing: what if there are spaces at the start of the -pattern? C<pack(" U*", @stuff)> will have C<U> as the first active -character, even though it's not the first thing in the pattern. In this -case, we have to advance C<patcopy> along with C<pat> when we see spaces: - - if (isSPACE(datumtype)) - continue; - -needs to become - - if (isSPACE(datumtype)) { - patcopy++; - continue; - } - -OK. That's the C part done. Now we must do two additional things before -this patch is ready to go: we've changed the behaviour of Perl, and so -we must document that change. We must also provide some more regression -tests to make sure our patch works and doesn't create a bug somewhere -else along the line. - -The regression tests for each operator live in F<t/op/>, and so we -make a copy of F<t/op/pack.t> to F<t/op/pack.t~>. Now we can add our -tests to the end. First, we'll test that the C<U> does indeed create -Unicode strings. - -t/op/pack.t has a sensible ok() function, but if it didn't we could -use the one from t/test.pl. - - require './test.pl'; - plan( tests => 159 ); - -so instead of this: - - print 'not ' unless "1.20.300.4000" eq sprintf "%vd", - pack("U*",1,20,300,4000); - print "ok $test\n"; $test++; +Please make sure you add the perldelta entry to the right section +within F<pod/perldelta.pod>. More information on how to write good +perldelta entries is available in the C<Style> section of +F<Porting/how_to_write_a_perldelta.pod>. -we can write the more sensible (see L<Test::More> for a full -explanation of is() and other testing functions). +=head2 What makes for a good patch? - is( "1.20.300.4000", sprintf "%vd", pack("U*",1,20,300,4000), - "U* produces Unicode" ); +New features and extensions to the language can be contentious. There +is no specific set of criteria which determine what features get added, +but here are some questions to consider when developing a patch: -Now we'll test that we got that space-at-the-beginning business right: +=head3 Does the concept match the general goals of Perl? - is( "1.20.300.4000", sprintf "%vd", pack(" U*",1,20,300,4000), - " with spaces at the beginning" ); +Our goals include, but are not limited to: -And finally we'll test that we don't make Unicode strings if C<U> is B<not> -the first active format: - - isnt( v1.20.300.4000, sprintf "%vd", pack("C0U*",1,20,300,4000), - "U* not first isn't Unicode" ); - -Mustn't forget to change the number of tests which appears at the top, -or else the automated tester will get confused. This will either look -like this: - - print "1..156\n"; - -or this: +=over 4 - plan( tests => 156 ); +=item 1. -We now compile up Perl, and run it through the test suite. Our new -tests pass, hooray! +Keep it fast, simple, and useful. -Finally, the documentation. The job is never done until the paperwork is -over, so let's describe the change we've just made. The relevant place -is F<pod/perlfunc.pod>; again, we make a copy, and then we'll insert -this text in the description of C<pack>: +=item 2. - =item * +Keep features/concepts as orthogonal as possible. - If the pattern begins with a C<U>, the resulting string will be treated - as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a string - with an initial C<U0>, and the bytes that follow will be interpreted as - Unicode characters. If you don't want this to happen, you can begin - your pattern with C<C0> (or anything else) to force Perl not to UTF-8 - encode your string, and then follow this with a C<U*> somewhere in your - pattern. +=item 3. -=head2 Patching a core module +No arbitrary limits (platforms, data sizes, cultures). -This works just like patching anything else, with an extra -consideration. Many core modules also live on CPAN. If this is so, -patch the CPAN version instead of the core and send the patch off to -the module maintainer (with a copy to p5p). This will help the module -maintainer keep the CPAN version in sync with the core version without -constantly scanning p5p. - -The list of maintainers of core modules is usefully documented in -F<Porting/Maintainers.pl>. - -=head2 Adding a new function to the core - -If, as part of a patch to fix a bug, or just because you have an -especially good idea, you decide to add a new function to the core, -discuss your ideas on p5p well before you start work. It may be that -someone else has already attempted to do what you are considering and -can give lots of good advice or even provide you with bits of code -that they already started (but never finished). - -You have to follow all of the advice given above for patching. It is -extremely important to test any addition thoroughly and add new tests -to explore all boundary conditions that your new function is expected -to handle. If your new function is used only by one module (e.g. toke), -then it should probably be named S_your_function (for static); on the -other hand, if you expect it to accessible from other functions in -Perl, you should name it Perl_your_function. See L<perlguts/Internal Functions> -for more details. +=item 4. -The location of any new code is also an important consideration. Don't -just create a new top level .c file and put your code there; you would -have to make changes to Configure (so the Makefile is created properly), -as well as possibly lots of include files. This is strictly pumpking -business. +Keep it open and exciting to use/patch/advocate Perl everywhere. -It is better to add your function to one of the existing top level -source code files, but your choice is complicated by the nature of -the Perl distribution. Only the files that are marked as compiled -static are located in the perl executable. Everything else is located -in the shared library (or DLL if you are running under WIN32). So, -for example, if a function was only used by functions located in -toke.c, then your code can go in toke.c. If, however, you want to call -the function from universal.c, then you should put your code in another -location, for example util.c. +=item 5. -In addition to writing your c-code, you will need to create an -appropriate entry in embed.pl describing your function, then run -'make regen_headers' to create the entries in the numerous header -files that perl needs to compile correctly. See L<perlguts/Internal Functions> -for information on the various options that you can set in embed.pl. -You will forget to do this a few (or many) times and you will get -warnings during the compilation phase. Make sure that you mention -this when you post your patch to P5P; the pumpking needs to know this. +Either assimilate new technologies, or build bridges to them. -When you write your new code, please be conscious of existing code -conventions used in the perl source files. See L<perlstyle> for -details. Although most of the guidelines discussed seem to focus on -Perl code, rather than c, they all apply (except when they don't ;). -Also see L<perlrepository> for lots of details about both formatting and -submitting patches of your changes. +=back -Lastly, TEST TEST TEST TEST TEST any code before posting to p5p. -Test on as many platforms as you can find. Test as many perl -Configure options as you can (e.g. MULTIPLICITY). If you have -profiling or memory tools, see L<EXTERNAL TOOLS FOR DEBUGGING PERL> -below for how to use them to further test your code. Remember that -most of the people on P5P are doing this on their own time and -don't have the time to debug your code. +=head3 Where is the implementation? -=head2 Writing a test +All the talk in the world is useless without an implementation. In +almost every case, the person or people who argue for a new feature +will be expected to be the ones who implement it. Porters capable of +coding new features have their own agendas, and are not available to +implement your (possibly good) idea. -Every module and built-in function has an associated test file (or -should...). If you add or change functionality, you have to write a -test. If you fix a bug, you have to write a test so that bug never -comes back. If you alter the docs, it would be nice to test what the -new documentation says. +=head3 Backwards compatibility -In short, if you submit a patch you probably also have to patch the -tests. +It's a cardinal sin to break existing Perl programs. New warnings can +be contentious--some say that a program that emits warnings is not +broken, while others say it is. Adding keywords has the potential to +break programs, changing the meaning of existing token sequences or +functions might break programs. -For modules, the test file is right next to the module itself. -F<lib/strict.t> tests F<lib/strict.pm>. This is a recent innovation, -so there are some snags (and it would be wonderful for you to brush -them out), but it basically works that way. Everything else lives in -F<t/>. +The Perl 5 core includes mechanisms to help porters make backwards +incompatible changes more compatible such as the L<feature> and +L<deprecate> modules. Please use them when appropriate. -If you add a new test directory under F<t/>, it is imperative that you -add that directory to F<t/HARNESS> and F<t/TEST>. +=head3 Could it be a module instead? -=over 3 +Perl 5 has extension mechanisms, modules and XS, specifically to avoid +the need to keep changing the Perl interpreter. You can write modules +that export functions, you can give those functions prototypes so they +can be called like built-in functions, you can even write XS code to +mess with the runtime data structures of the Perl interpreter if you +want to implement really complicated things. -=item F<t/base/> +Whenever possible, new features should be prototyped in a CPAN module +before they will be considered for the core. -Testing of the absolute basic functionality of Perl. Things like -C<if>, basic file reads and writes, simple regexes, etc. These are -run first in the test suite and if any of them fail, something is -I<really> broken. +=head3 Is the feature generic enough? -=item F<t/cmd/> +Is this something that only the submitter wants added to the language, +or is it broadly useful? Sometimes, instead of adding a feature with a +tight focus, the porters might decide to wait until someone implements +the more generalized feature. -These test the basic control structures, C<if/else>, C<while>, -subroutines, etc. +=head3 Does it potentially introduce new bugs? -=item F<t/comp/> +Radical rewrites of large chunks of the Perl interpreter have the +potential to introduce new bugs. -Tests basic issues of how Perl parses and compiles itself. +=head3 How big is it? -=item F<t/io/> +The smaller and more localized the change, the better. Similarly, a +series of small patches is greatly preferred over a single large patch. -Tests for built-in IO functions, including command line arguments. +=head3 Does it preclude other desirable features? -=item F<t/lib/> +A patch is likely to be rejected if it closes off future avenues of +development. For instance, a patch that placed a true and final +interpretation on prototypes is likely to be rejected because there are +still options for the future of prototypes that haven't been addressed. -The old home for the module tests, you shouldn't put anything new in -here. There are still some bits and pieces hanging around in here -that need to be moved. Perhaps you could move them? Thanks! +=head3 Is the implementation robust? -=item F<t/mro/> +Good patches (tight code, complete, correct) stand more chance of going +in. Sloppy or incorrect patches might be placed on the back burner +until the pumpking has time to fix, or might be discarded altogether +without further notice. -Tests for perl's method resolution order implementations -(see L<mro>). +=head3 Is the implementation generic enough to be portable? -=item F<t/op/> +The worst patches make use of system-specific features. It's highly +unlikely that non-portable additions to the Perl language will be +accepted. -Tests for perl's built in functions that don't fit into any of the -other directories. +=head3 Is the implementation tested? -=item F<t/re/> +Patches which change behaviour (fixing bugs or introducing new +features) must include regression tests to verify that everything works +as expected. -Tests for regex related functions or behaviour. (These used to live -in t/op). +Without tests provided by the original author, how can anyone else +changing perl in the future be sure that they haven't unwittingly +broken the behaviour the patch implements? And without tests, how can +the patch's author be confident that his/her hard work put into the +patch won't be accidentally thrown away by someone in the future? -=item F<t/run/> +=head3 Is there enough documentation? -Testing features of how perl actually runs, including exit codes and -handling of PERL* environment variables. +Patches without documentation are probably ill-thought out or +incomplete. No features can be added or changed without documentation, +so submitting a patch for the appropriate pod docs as well as the +source code is important. -=item F<t/uni/> +=head3 Is there another way to do it? -Tests for the core support of Unicode. +Larry said "Although the Perl Slogan is I<There's More Than One Way to +Do It>, I hesitate to make 10 ways to do something". This is a tricky +heuristic to navigate, though--one man's essential addition is another +man's pointless cruft. -=item F<t/win32/> +=head3 Does it create too much work? -Windows-specific tests. +Work for the pumpking, work for Perl programmers, work for module +authors, ... Perl is supposed to be easy. -=item F<t/x2p> +=head3 Patches speak louder than words -A test suite for the s2p converter. +Working code is always preferred to pie-in-the-sky ideas. A patch to +add a feature stands a much higher chance of making it to the language +than does a random feature request, no matter how fervently argued the +request might be. This ties into "Will it be useful?", as the fact that +someone took the time to make the patch demonstrates a strong desire +for the feature. -=back +=head1 TESTING The core uses the same testing style as the rest of Perl, a simple "ok/not ok" run through Test::Harness, but there are a few special considerations. -There are three ways to write a test in the core. Test::More, -t/test.pl and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">. The +There are three ways to write a test in the core. L<Test::More>, +F<t/test.pl> and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">. The decision of which to use depends on what part of the test suite you're -working on. This is a measure to prevent a high-level failure (such -as Config.pm breaking) from causing basic functionality tests to fail. +working on. This is a measure to prevent a high-level failure (such as +Config.pm breaking) from causing basic functionality tests to fail. + +The F<t/test.pl> library provides some of the features of +L<Test::More>, but avoids loading most modules and uses as few core +features as possible. + If you write your own test, use the L<Test Anything Protocol|TAP>. =over 4 -=item t/base t/comp +=item * F<t/base> and F<t/comp> Since we don't know if require works, or even subroutines, use ad hoc -tests for these two. Step carefully to avoid using the feature being +tests for these two. Step carefully to avoid using the feature being tested. -=item t/cmd t/run t/io t/op +=item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op> Now that basic require() and subroutines are tested, you can use the -t/test.pl library which emulates the important features of Test::More -while using a minimum of core features. +F<t/test.pl> library. -You can also conditionally use certain libraries like Config, but be +You can also use certain libraries like Config conditionally, but be sure to skip the test gracefully if it's not there. -=item t/lib ext lib +=item * Everything else -Now that the core of Perl is tested, Test::More can be used. You can -also use the full suite of core modules in the tests. +Now that the core of Perl is tested, L<Test::More> can and should be +used. You can also use the full suite of core modules in the tests. =back -When you say "make test" Perl uses the F<t/TEST> program to run the -test suite (except under Win32 where it uses F<t/harness> instead.) -All tests are run from the F<t/> directory, B<not> the directory -which contains the test. This causes some problems with the tests -in F<lib/>, so here's some opportunity for some patching. +When you say "make test", Perl uses the F<t/TEST> program to run the +test suite (except under Win32 where it uses F<t/harness> instead). All +tests are run from the F<t/> directory, B<not> the directory which +contains the test. This causes some problems with the tests in F<lib/>, +so here's some opportunity for some patching. -You must be triply conscious of cross-platform concerns. This usually -boils down to using File::Spec and avoiding things like C<fork()> and -C<system()> unless absolutely necessary. +You must be triply conscious of cross-platform concerns. This usually +boils down to using L<File::Spec> and avoiding things like C<fork()> +and C<system()> unless absolutely necessary. -=head2 Special Make Test Targets +=head2 Special C<make test> targets There are various special make targets that can be used to test Perl -slightly differently than the standard "test" target. Not all them -are expected to give a 100% success rate. Many of them have several +slightly differently than the standard "test" target. Not all them are +expected to give a 100% success rate. Many of them have several aliases, and many of them are not available on certain operating systems. =over 4 -=item coretest +=item * test_porting + +This runs some basic sanity tests on the source tree and helps catch +basic errors before you submit a patch. + +=item * coretest Run F<perl> on all core tests (F<t/*> and F<lib/[a-z]*> pragma tests). (Not available on Win32) -=item test.deparse +=item * test.deparse -Run all the tests through B::Deparse. Not all tests will succeed. +Run all the tests through L<B::Deparse>. Not all tests will succeed. (Not available on Win32) -=item test.taintwarn +=item * test.taintwarn -Run all tests with the B<-t> command-line switch. Not all tests -are expected to succeed (until they're specifically fixed, of course). +Run all tests with the B<-t> command-line switch. Not all tests are +expected to succeed (until they're specifically fixed, of course). (Not available on Win32) -=item minitest +=item * minitest Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>, F<t/op>, F<t/uni> and F<t/mro> tests. -=item test.valgrind check.valgrind utest.valgrind ucheck.valgrind +=item * test.valgrind check.valgrind utest.valgrind ucheck.valgrind (Only in Linux) Run all the tests using the memory leak + naughty -memory access tool "valgrind". The log files will be named +memory access tool "valgrind". The log files will be named F<testname.valgrind>. -=item test.third check.third utest.third ucheck.third - -(Only in Tru64) Run all the tests using the memory leak + naughty -memory access tool "Third Degree". The log files will be named -F<perl.3log.testname>. - -=item test.torture torturetest +=item * test.torture torturetest -Run all the usual tests and some extra tests. As of Perl 5.8.0 the -only extra tests are Abigail's JAPHs, F<t/japh/abigail.t>. +Run all the usual tests and some extra tests. As of Perl 5.8.0, the only +extra tests are Abigail's JAPHs, F<t/japh/abigail.t>. You can also run the torture test with F<t/harness> by giving C<-torture> argument to F<t/harness>. -=item utest ucheck test.utf8 check.utf8 +=item * utest ucheck test.utf8 check.utf8 -Run all the tests with -Mutf8. Not all tests will succeed. +Run all the tests with -Mutf8. Not all tests will succeed. (Not available on Win32) -=item minitest.utf16 test.utf16 +=item * minitest.utf16 test.utf16 Runs the tests with UTF-16 encoded scripts, encoded with different versions of this encoding. -C<make utest.utf16> runs the test suite with a combination of C<-utf8> and -C<-utf16> arguments to F<t/TEST>. +C<make utest.utf16> runs the test suite with a combination of C<-utf8> +and C<-utf16> arguments to F<t/TEST>. (Not available on Win32) -=item test_harness +=item * test_harness -Run the test suite with the F<t/harness> controlling program, instead of -F<t/TEST>. F<t/harness> is more sophisticated, and uses the +Run the test suite with the F<t/harness> controlling program, instead +of F<t/TEST>. F<t/harness> is more sophisticated, and uses the L<Test::Harness> module, thus using this test target supposes that perl mostly works. The main advantage for our purposes is that it prints a detailed summary of failed tests at the end. Also, unlike F<t/TEST>, it doesn't redirect stderr to stdout. -Note that under Win32 F<t/harness> is always used instead of F<t/TEST>, so -there is no special "test_harness" target. +Note that under Win32 F<t/harness> is always used instead of F<t/TEST>, +so there is no special "test_harness" target. -Under Win32's "test" target you may use the TEST_SWITCHES and TEST_FILES -environment variables to control the behaviour of F<t/harness>. This means -you can say +Under Win32's "test" target you may use the TEST_SWITCHES and +TEST_FILES environment variables to control the behaviour of +F<t/harness>. This means you can say nmake test TEST_FILES="op/*.t" nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t" -=item Parallel tests +=item * test-notty test_notty + +Sets PERL_SKIP_TTY_TEST to true before running normal test. + +=back + +=head2 Parallel tests The core distribution can now run its regression tests in parallel on -Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> in -your environment to the number of tests to run in parallel, and run +Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> +in your environment to the number of tests to run in parallel, and run C<make test_harness>. On a Bourne-like shell, this can be done as TEST_JOBS=3 make test_harness # Run 3 tests in parallel -An environment variable is used, rather than parallel make itself, because -L<TAP::Harness> needs to be able to schedule individual non-conflicting test -scripts itself, and there is no standard interface to C<make> utilities to -interact with their job schedulers. +An environment variable is used, rather than parallel make itself, +because L<TAP::Harness> needs to be able to schedule individual +non-conflicting test scripts itself, and there is no standard interface +to C<make> utilities to interact with their job schedulers. Note that currently some test scripts may fail when run in parallel (most -notably C<ext/IO/t/io_dir.t>). If necessary run just the failing scripts +notably C<ext/IO/t/io_dir.t>). If necessary, run just the failing scripts again sequentially and see if the failures go away. -=item test-notty test_notty - -Sets PERL_SKIP_TTY_TEST to true before running normal test. - -=back =head2 Running tests by hand -You can run part of the test suite by hand by using one the following -commands from the F<t/> directory : +You can run part of the test suite by hand by using one of the following +commands from the F<t/> directory: ./perl -I../lib TEST list-of-.t-files @@ -1995,71 +842,73 @@ or ./perl -I../lib harness list-of-.t-files -(if you don't specify test scripts, the whole test suite will be run.) +(If you don't specify test scripts, the whole test suite will be run.) -=head3 Using t/harness for testing +=head2 Using F<t/harness> for testing -If you use C<harness> for testing you have several command line options +If you use C<harness> for testing, you have several command line options available to you. The arguments are as follows, and are in the order that they must appear if used together. harness -v -torture -re=pattern LIST OF FILES TO TEST harness -v -torture -re LIST OF PATTERNS TO MATCH -If C<LIST OF FILES TO TEST> is omitted the file list is obtained from +If C<LIST OF FILES TO TEST> is omitted, the file list is obtained from the manifest. The file list may include shell wildcards which will be expanded out. =over 4 -=item -v +=item * -v Run the tests under verbose mode so you can see what tests were run, and debug output. -=item -torture +=item * -torture Run the torture tests as well as the normal set. -=item -re=PATTERN +=item * -re=PATTERN -Filter the file list so that all the test files run match PATTERN. -Note that this form is distinct from the B<-re LIST OF PATTERNS> form below +Filter the file list so that all the test files run match PATTERN. Note +that this form is distinct from the B<-re LIST OF PATTERNS> form below in that it allows the file list to be provided as well. -=item -re LIST OF PATTERNS +=item * -re LIST OF PATTERNS Filter the file list so that all the test files run match -/(LIST|OF|PATTERNS)/. Note that with this form the patterns -are joined by '|' and you cannot supply a list of files, instead -the test files are obtained from the MANIFEST. +/(LIST|OF|PATTERNS)/. Note that with this form the patterns are joined +by '|' and you cannot supply a list of files, instead the test files +are obtained from the MANIFEST. =back You can run an individual test by a command similar to - ./perl -I../lib patho/to/foo.t + ./perl -I../lib path/to/foo.t except that the harnesses set up some environment variables that may -affect the execution of the test : +affect the execution of the test: =over 4 -=item PERL_CORE=1 +=item * PERL_CORE=1 -indicates that we're running this test part of the perl core test suite. -This is useful for modules that have a dual life on CPAN. +indicates that we're running this test as part of the perl core test +suite. This is useful for modules that have a dual life on CPAN. -=item PERL_DESTRUCT_LEVEL=2 +=item * PERL_DESTRUCT_LEVEL=2 -is set to 2 if it isn't set already (see L</PERL_DESTRUCT_LEVEL>) +is set to 2 if it isn't set already (see +L<perlhacktips/PERL_DESTRUCT_LEVEL>). -=item PERL +=item * PERL -(used only by F<t/TEST>) if set, overrides the path to the perl executable -that should be used to run the tests (the default being F<./perl>). +(used only by F<t/TEST>) if set, overrides the path to the perl +executable that should be used to run the tests (the default being +F<./perl>). -=item PERL_SKIP_TTY_TEST +=item * PERL_SKIP_TTY_TEST if set, tells to skip the tests that need a terminal. It's actually set automatically by the Makefile, but can also be forced artificially by @@ -2071,1331 +920,211 @@ running 'make test_notty'. =over 4 -=item PERL_TEST_Net_Ping +=item * PERL_TEST_Net_Ping -Setting this variable runs all the Net::Ping modules tests, -otherwise some tests that interact with the outside world are skipped. -See L<perl58delta>. +Setting this variable runs all the Net::Ping modules tests, otherwise +some tests that interact with the outside world are skipped. See +L<perl58delta>. -=item PERL_TEST_NOVREXX +=item * PERL_TEST_NOVREXX Setting this variable skips the vrexx.t tests for OS2::REXX. -=item PERL_TEST_NUMCONVERTS +=item * PERL_TEST_NUMCONVERTS This sets a variable in op/numconvert.t. =back -See also the documentation for the Test and Test::Harness modules, -for more environment variables that affect testing. - -=head2 Common problems when patching Perl source code - -Perl source plays by ANSI C89 rules: no C99 (or C++) extensions. In -some cases we have to take pre-ANSI requirements into consideration. -You don't care about some particular platform having broken Perl? -I hear there is still a strong demand for J2EE programmers. - -=head2 Perl environment problems - -=over 4 - -=item * - -Not compiling with threading - -Compiling with threading (-Duseithreads) completely rewrites -the function prototypes of Perl. You better try your changes -with that. Related to this is the difference between "Perl_-less" -and "Perl_-ly" APIs, for example: - - Perl_sv_setiv(aTHX_ ...); - sv_setiv(...); - -The first one explicitly passes in the context, which is needed for e.g. -threaded builds. The second one does that implicitly; do not get them -mixed. If you are not passing in a aTHX_, you will need to do a dTHX -(or a dVAR) as the first thing in the function. - -See L<perlguts/"How multiple interpreters and concurrency are supported"> -for further discussion about context. - -=item * - -Not compiling with -DDEBUGGING - -The DEBUGGING define exposes more code to the compiler, -therefore more ways for things to go wrong. You should try it. - -=item * - -Introducing (non-read-only) globals - -Do not introduce any modifiable globals, truly global or file static. -They are bad form and complicate multithreading and other forms of -concurrency. The right way is to introduce them as new interpreter -variables, see F<intrpvar.h> (at the very end for binary compatibility). - -Introducing read-only (const) globals is okay, as long as you verify -with e.g. C<nm libperl.a|egrep -v ' [TURtr] '> (if your C<nm> has -BSD-style output) that the data you added really is read-only. -(If it is, it shouldn't show up in the output of that command.) - -If you want to have static strings, make them constant: - - static const char etc[] = "..."; - -If you want to have arrays of constant strings, note carefully -the right combination of C<const>s: - - static const char * const yippee[] = - {"hi", "ho", "silver"}; - -There is a way to completely hide any modifiable globals (they are all -moved to heap), the compilation setting C<-DPERL_GLOBAL_STRUCT_PRIVATE>. -It is not normally used, but can be used for testing, read more -about it in L<perlguts/"Background and PERL_IMPLICIT_CONTEXT">. - -=item * - -Not exporting your new function - -Some platforms (Win32, AIX, VMS, OS/2, to name a few) require any -function that is part of the public API (the shared Perl library) -to be explicitly marked as exported. See the discussion about -F<embed.pl> in L<perlguts>. - -=item * - -Exporting your new function - -The new shiny result of either genuine new functionality or your -arduous refactoring is now ready and correctly exported. So what -could possibly go wrong? - -Maybe simply that your function did not need to be exported in the -first place. Perl has a long and not so glorious history of exporting -functions that it should not have. - -If the function is used only inside one source code file, make it -static. See the discussion about F<embed.pl> in L<perlguts>. - -If the function is used across several files, but intended only for -Perl's internal use (and this should be the common case), do not -export it to the public API. See the discussion about F<embed.pl> -in L<perlguts>. - -=back - -=head2 Portability problems - -The following are common causes of compilation and/or execution -failures, not common to Perl as such. The C FAQ is good bedtime -reading. Please test your changes with as many C compilers and -platforms as possible; we will, anyway, and it's nice to save -oneself from public embarrassment. - -If using gcc, you can add the C<-std=c89> option which will hopefully -catch most of these unportabilities. (However it might also catch -incompatibilities in your system's header files.) - -Use the Configure C<-Dgccansipedantic> flag to enable the gcc -C<-ansi -pedantic> flags which enforce stricter ANSI rules. - -If using the C<gcc -Wall> note that not all the possible warnings -(like C<-Wunitialized>) are given unless you also compile with C<-O>. - -Note that if using gcc, starting from Perl 5.9.5 the Perl core source -code files (the ones at the top level of the source code distribution, -but not e.g. the extensions under ext/) are automatically compiled -with as many as possible of the C<-std=c89>, C<-ansi>, C<-pedantic>, -and a selection of C<-W> flags (see cflags.SH). - -Also study L<perlport> carefully to avoid any bad assumptions -about the operating system, filesystems, and so forth. - -You may once in a while try a "make microperl" to see whether we -can still compile Perl with just the bare minimum of interfaces. -(See README.micro.) - -Do not assume an operating system indicates a certain compiler. - -=over 4 - -=item * - -Casting pointers to integers or casting integers to pointers - - void castaway(U8* p) - { - IV i = p; - -or - - void castaway(U8* p) - { - IV i = (IV)p; - -Both are bad, and broken, and unportable. Use the PTR2IV() -macro that does it right. (Likewise, there are PTR2UV(), PTR2NV(), -INT2PTR(), and NUM2PTR().) - -=item * - -Casting between data function pointers and data pointers - -Technically speaking casting between function pointers and data -pointers is unportable and undefined, but practically speaking -it seems to work, but you should use the FPTR2DPTR() and DPTR2FPTR() -macros. Sometimes you can also play games with unions. - -=item * - -Assuming sizeof(int) == sizeof(long) - -There are platforms where longs are 64 bits, and platforms where ints -are 64 bits, and while we are out to shock you, even platforms where -shorts are 64 bits. This is all legal according to the C standard. -(In other words, "long long" is not a portable way to specify 64 bits, -and "long long" is not even guaranteed to be any wider than "long".) - -Instead, use the definitions IV, UV, IVSIZE, I32SIZE, and so forth. -Avoid things like I32 because they are B<not> guaranteed to be -I<exactly> 32 bits, they are I<at least> 32 bits, nor are they -guaranteed to be B<int> or B<long>. If you really explicitly need -64-bit variables, use I64 and U64, but only if guarded by HAS_QUAD. - -=item * - -Assuming one can dereference any type of pointer for any type of data - - char *p = ...; - long pony = *p; /* BAD */ - -Many platforms, quite rightly so, will give you a core dump instead -of a pony if the p happens not be correctly aligned. - -=item * - -Lvalue casts - - (int)*p = ...; /* BAD */ - -Simply not portable. Get your lvalue to be of the right type, -or maybe use temporary variables, or dirty tricks with unions. - -=item * - -Assume B<anything> about structs (especially the ones you -don't control, like the ones coming from the system headers) - -=over 8 - -=item * - -That a certain field exists in a struct - -=item * - -That no other fields exist besides the ones you know of - -=item * - -That a field is of certain signedness, sizeof, or type - -=item * - -That the fields are in a certain order - -=over 8 - -=item * - -While C guarantees the ordering specified in the struct definition, -between different platforms the definitions might differ - -=back - -=item * - -That the sizeof(struct) or the alignments are the same everywhere - -=over 8 - -=item * - -There might be padding bytes between the fields to align the fields - -the bytes can be anything - -=item * - -Structs are required to be aligned to the maximum alignment required -by the fields - which for native types is for usually equivalent to -sizeof() of the field - -=back - -=back - -=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 being changed starting 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) ... \ - #ifdef BURGLE_OLD_STYLE /* BAD */ - ... do it the old way ... \ - #else - ... do it the new way ... \ - #endif - -You cannot portably "stack" cpp directives. For example in the above -you need two separate BURGLE() #defines, one for each #ifdef branch. - -=item * - -Adding non-comment stuff after #endif or #else - - #ifdef SNOSH - ... - #else !SNOSH /* BAD */ - ... - #endif SNOSH /* BAD */ - -The #endif and #else cannot portably have anything non-comment after -them. If you want to document what is going (which is a good idea -especially if the branches are long), use (C) comments: - - #ifdef SNOSH - ... - #else /* !SNOSH */ - ... - #endif /* SNOSH */ - -The gcc option C<-Wendif-labels> warns about the bad variant -(by default on starting from Perl 5.9.4). - -=item * - -Having a comma after the last element of an enum list - - enum color { - CERULEAN, - CHARTREUSE, - CINNABAR, /* BAD */ - }; - -is not portable. Leave out the last comma. - -Also note that whether enums are implicitly morphable to ints -varies between compilers, you might need to (int). - -=item * - -Using //-comments - - // This function bamfoodles the zorklator. /* BAD */ - -That is C99 or C++. Perl is C89. Using the //-comments is silently -allowed by many C compilers but cranking up the ANSI C89 strictness -(which we like to do) causes the compilation to fail. - -=item * - -Mixing declarations and code - - void zorklator() - { - int n = 3; - set_zorkmids(n); /* BAD */ - int q = 4; - -That is C99 or C++. Some C compilers allow that, but you shouldn't. - -The gcc option C<-Wdeclaration-after-statements> scans for such problems -(by default on starting from Perl 5.9.4). - -=item * - -Introducing variables inside for() - - for(int i = ...; ...; ...) { /* BAD */ - -That is C99 or C++. While it would indeed be awfully nice to have that -also in C89, to limit the scope of the loop variable, alas, we cannot. - -=item * - -Mixing signed char pointers with unsigned char pointers - - int foo(char *s) { ... } - ... - unsigned char *t = ...; /* Or U8* t = ... */ - foo(t); /* BAD */ - -While this is legal practice, it is certainly dubious, and downright -fatal in at least one platform: for example VMS cc considers this a -fatal error. One cause for people often making this mistake is that a -"naked char" and therefore dereferencing a "naked char pointer" have -an undefined signedness: it depends on the compiler and the flags of -the compiler and the underlying platform whether the result is signed -or unsigned. For this very same reason using a 'char' as an array -index is bad. - -=item * - -Macros that have string constants and their arguments as substrings of -the string constants - - #define FOO(n) printf("number = %d\n", n) /* BAD */ - FOO(10); - -Pre-ANSI semantics for that was equivalent to - - printf("10umber = %d\10"); - -which is probably not what you were expecting. Unfortunately at least -one reasonably common and modern C compiler does "real backward -compatibility" here, in AIX that is what still happens even though the -rest of the AIX compiler is very happily C89. - -=item * - -Using printf formats for non-basic C types - - IV i = ...; - printf("i = %d\n", i); /* BAD */ - -While this might by accident work in some platform (where IV happens -to be an C<int>), in general it cannot. IV might be something larger. -Even worse the situation is with more specific types (defined by Perl's -configuration step in F<config.h>): - - Uid_t who = ...; - printf("who = %d\n", who); /* BAD */ - -The problem here is that Uid_t might be not only not C<int>-wide -but it might also be unsigned, in which case large uids would be -printed as negative values. - -There is no simple solution to this because of printf()'s limited -intelligence, but for many types the right format is available as -with either 'f' or '_f' suffix, for example: - - IVdf /* IV in decimal */ - UVxf /* UV is hexadecimal */ - - printf("i = %"IVdf"\n", i); /* The IVdf is a string constant. */ - - Uid_t_f /* Uid_t in decimal */ - - printf("who = %"Uid_t_f"\n", who); - -Or you can try casting to a "wide enough" type: - - printf("i = %"IVdf"\n", (IV)something_very_small_and_signed); - -Also remember that the C<%p> format really does require a void pointer: - - U8* p = ...; - printf("p = %p\n", (void*)p); - -The gcc option C<-Wformat> scans for such problems. - -=item * - -Blindly using variadic macros - -gcc has had them for a while with its own syntax, and C99 brought -them with a standardized syntax. Don't use the former, and use -the latter only if the HAS_C99_VARIADIC_MACROS is defined. - -=item * - -Blindly passing va_list - -Not all platforms support passing va_list to further varargs (stdarg) -functions. The right thing to do is to copy the va_list using the -Perl_va_copy() if the NEED_VA_COPY is defined. - -=item * - -Using gcc statement expressions - - val = ({...;...;...}); /* BAD */ - -While a nice extension, it's not portable. The Perl code does -admittedly use them if available to gain some extra speed -(essentially as a funky form of inlining), but you shouldn't. - -=item * - -Binding together several statements in a macro - -Use the macros STMT_START and STMT_END. - - STMT_START { - ... - } STMT_END - -=item * - -Testing for operating systems or versions when should be testing for features - - #ifdef __FOONIX__ /* BAD */ - foo = quux(); - #endif - -Unless you know with 100% certainty that quux() is only ever available -for the "Foonix" operating system B<and> that is available B<and> -correctly working for B<all> past, present, B<and> future versions of -"Foonix", the above is very wrong. This is more correct (though still -not perfect, because the below is a compile-time check): - - #ifdef HAS_QUUX - foo = quux(); - #endif - -How does the HAS_QUUX become defined where it needs to be? Well, if -Foonix happens to be Unixy enough to be able to run the Configure -script, and Configure has been taught about detecting and testing -quux(), the HAS_QUUX will be correctly defined. In other platforms, -the corresponding configuration step will hopefully do the same. - -In a pinch, if you cannot wait for Configure to be educated, -or if you have a good hunch of where quux() might be available, -you can temporarily try the following: - - #if (defined(__FOONIX__) || defined(__BARNIX__)) - # define HAS_QUUX - #endif - - ... - - #ifdef HAS_QUUX - foo = quux(); - #endif - -But in any case, try to keep the features and operating systems separate. - -=back - -=head2 Problematic System Interfaces - -=over 4 - -=item * - -malloc(0), realloc(0), calloc(0, 0) are non-portable. To be portable -allocate at least one byte. (In general you should rarely need to -work at this low level, but instead use the various malloc wrappers.) - -=item * - -snprintf() - the return type is unportable. Use my_snprintf() instead. - -=back - -=head2 Security problems - -Last but not least, here are various tips for safer coding. - -=over 4 - -=item * - -Do not use gets() - -Or we will publicly ridicule you. Seriously. - -=item * - -Do not use strcpy() or strcat() or strncpy() or strncat() - -Use my_strlcpy() and my_strlcat() instead: they either use the native -implementation, or Perl's own implementation (borrowed from the public -domain implementation of INN). - -=item * - -Do not use sprintf() or vsprintf() - -If you really want just plain byte strings, use my_snprintf() -and my_vsnprintf() instead, which will try to use snprintf() and -vsnprintf() if those safer APIs are available. If you want something -fancier than a plain byte string, use SVs and Perl_sv_catpvf(). - -=back - -=head1 EXTERNAL TOOLS FOR DEBUGGING PERL - -Sometimes it helps to use external tools while debugging and -testing Perl. This section tries to guide you through using -some common testing and debugging tools with Perl. This is -meant as a guide to interfacing these tools with Perl, not -as any kind of guide to the use of the tools themselves. - -B<NOTE 1>: Running under memory debuggers such as Purify, valgrind, or -Third Degree greatly slows down the execution: seconds become minutes, -minutes become hours. For example as of Perl 5.8.1, the -ext/Encode/t/Unicode.t takes extraordinarily long to complete under -e.g. Purify, Third Degree, and valgrind. Under valgrind it takes more -than six hours, even on a snappy computer. The said test must be -doing something that is quite unfriendly for memory debuggers. If you -don't feel like waiting, that you can simply kill away the perl -process. - -B<NOTE 2>: To minimize the number of memory leak false alarms (see -L</PERL_DESTRUCT_LEVEL> for more information), you have to set the -environment variable PERL_DESTRUCT_LEVEL to 2. - -For csh-like shells: - - setenv PERL_DESTRUCT_LEVEL 2 - -For Bourne-type shells: - - PERL_DESTRUCT_LEVEL=2 - export PERL_DESTRUCT_LEVEL - -In Unixy environments you can also use the C<env> command: - - env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ... - -B<NOTE 3>: There are known memory leaks when there are compile-time -errors within eval or require, seeing C<S_doeval> in the call stack -is a good sign of these. Fixing these leaks is non-trivial, -unfortunately, but they must be fixed eventually. - -B<NOTE 4>: L<DynaLoader> will not clean up after itself completely -unless Perl is built with the Configure option -C<-Accflags=-DDL_UNLOAD_ALL_AT_EXIT>. - -=head2 Rational Software's Purify - -Purify is a commercial tool that is helpful in identifying -memory overruns, wild pointers, memory leaks and other such -badness. Perl must be compiled in a specific way for -optimal testing with Purify. Purify is available under -Windows NT, Solaris, HP-UX, SGI, and Siemens Unix. - -=head2 Purify on Unix - -On Unix, Purify creates a new Perl binary. To get the most -benefit out of Purify, you should create the perl to Purify -using: - - sh Configure -Accflags=-DPURIFY -Doptimize='-g' \ - -Uusemymalloc -Dusemultiplicity +See also the documentation for the Test and Test::Harness modules, for +more environment variables that affect testing. -where these arguments mean: +=head1 MORE READING FOR GUTS HACKERS -=over 4 - -=item -Accflags=-DPURIFY - -Disables Perl's arena memory allocation functions, as well as -forcing use of memory allocation functions derived from the -system malloc. - -=item -Doptimize='-g' - -Adds debugging information so that you see the exact source -statements where the problem occurs. Without this flag, all -you will see is the source filename of where the error occurred. - -=item -Uusemymalloc - -Disable Perl's malloc so that Purify can more closely monitor -allocations and leaks. Using Perl's malloc will make Purify -report most leaks in the "potential" leaks category. - -=item -Dusemultiplicity - -Enabling the multiplicity option allows perl to clean up -thoroughly when the interpreter shuts down, which reduces the -number of bogus leak reports from Purify. - -=back - -Once you've compiled a perl suitable for Purify'ing, then you -can just: - - make pureperl - -which creates a binary named 'pureperl' that has been Purify'ed. -This binary is used in place of the standard 'perl' binary -when you want to debug Perl memory problems. - -As an example, to show any memory leaks produced during the -standard Perl testset you would create and run the Purify'ed -perl as: - - make pureperl - cd t - ../pureperl -I../lib harness - -which would run Perl on test.pl and report any memory problems. - -Purify outputs messages in "Viewer" windows by default. If -you don't have a windowing environment or if you simply -want the Purify output to unobtrusively go to a log file -instead of to the interactive window, use these following -options to output to the log file "perl.log": - - setenv PURIFYOPTIONS "-chain-length=25 -windows=no \ - -log-file=perl.log -append-logfile=yes" - -If you plan to use the "Viewer" windows, then you only need this option: - - setenv PURIFYOPTIONS "-chain-length=25" - -In Bourne-type shells: - - PURIFYOPTIONS="..." - export PURIFYOPTIONS - -or if you have the "env" utility: - - env PURIFYOPTIONS="..." ../pureperl ... - -=head2 Purify on NT - -Purify on Windows NT instruments the Perl binary 'perl.exe' -on the fly. There are several options in the makefile you -should change to get the most use out of Purify: - -=over 4 - -=item DEFINES - -You should add -DPURIFY to the DEFINES line so the DEFINES -line looks something like: - - DEFINES = -DWIN32 -D_CONSOLE -DNO_STRICT $(CRYPT_FLAG) -DPURIFY=1 - -to disable Perl's arena memory allocation functions, as -well as to force use of memory allocation functions derived -from the system malloc. - -=item USE_MULTI = define - -Enabling the multiplicity option allows perl to clean up -thoroughly when the interpreter shuts down, which reduces the -number of bogus leak reports from Purify. - -=item #PERL_MALLOC = define - -Disable Perl's malloc so that Purify can more closely monitor -allocations and leaks. Using Perl's malloc will make Purify -report most leaks in the "potential" leaks category. - -=item CFG = Debug - -Adds debugging information so that you see the exact source -statements where the problem occurs. Without this flag, all -you will see is the source filename of where the error occurred. - -=back - -As an example, to show any memory leaks produced during the -standard Perl testset you would create and run Purify as: - - cd win32 - make - cd ../t - purify ../perl -I../lib harness - -which would instrument Perl in memory, run Perl on test.pl, -then finally report any memory problems. - -=head2 valgrind - -The excellent valgrind tool can be used to find out both memory leaks -and illegal memory accesses. As of version 3.3.0, Valgrind only -supports Linux on x86, x86-64 and PowerPC. The special "test.valgrind" -target can be used to run the tests under valgrind. Found errors -and memory leaks are logged in files named F<testfile.valgrind>. - -Valgrind also provides a cachegrind tool, invoked on perl as: - - VG_OPTS=--tool=cachegrind make test.valgrind - -As system libraries (most notably glibc) are also triggering errors, -valgrind allows to suppress such errors using suppression files. The -default suppression file that comes with valgrind already catches a lot -of them. Some additional suppressions are defined in F<t/perl.supp>. - -To get valgrind and for more information see - - http://developer.kde.org/~sewardj/ - -=head2 Compaq's/Digital's/HP's Third Degree - -Third Degree is a tool for memory leak detection and memory access checks. -It is one of the many tools in the ATOM toolkit. The toolkit is only -available on Tru64 (formerly known as Digital UNIX formerly known as -DEC OSF/1). - -When building Perl, you must first run Configure with -Doptimize=-g -and -Uusemymalloc flags, after that you can use the make targets -"perl.third" and "test.third". (What is required is that Perl must be -compiled using the C<-g> flag, you may need to re-Configure.) - -The short story is that with "atom" you can instrument the Perl -executable to create a new executable called F<perl.third>. When the -instrumented executable is run, it creates a log of dubious memory -traffic in file called F<perl.3log>. See the manual pages of atom and -third for more information. The most extensive Third Degree -documentation is available in the Compaq "Tru64 UNIX Programmer's -Guide", chapter "Debugging Programs with Third Degree". - -The "test.third" leaves a lot of files named F<foo_bar.3log> in the t/ -subdirectory. There is a problem with these files: Third Degree is so -effective that it finds problems also in the system libraries. -Therefore you should used the Porting/thirdclean script to cleanup -the F<*.3log> files. - -There are also leaks that for given certain definition of a leak, -aren't. See L</PERL_DESTRUCT_LEVEL> for more information. - -=head2 PERL_DESTRUCT_LEVEL - -If you want to run any of the tests yourself manually using e.g. -valgrind, or the pureperl or perl.third executables, please note that -by default perl B<does not> explicitly cleanup all the memory it has -allocated (such as global memory arenas) but instead lets the exit() -of the whole program "take care" of such allocations, also known as -"global destruction of objects". - -There is a way to tell perl to do complete cleanup: set the -environment variable PERL_DESTRUCT_LEVEL to a non-zero value. -The t/TEST wrapper does set this to 2, and this is what you -need to do too, if you don't want to see the "global leaks": -For example, for "third-degreed" Perl: - - env PERL_DESTRUCT_LEVEL=2 ./perl.third -Ilib t/foo/bar.t - -(Note: the mod_perl apache module uses also this environment variable -for its own purposes and extended its semantics. Refer to the mod_perl -documentation for more information. Also, spawned threads do the -equivalent of setting this variable to the value 1.) - -If, at the end of a run you get the message I<N scalars leaked>, you can -recompile with C<-DDEBUG_LEAKING_SCALARS>, which will cause the addresses -of all those leaked SVs to be dumped along with details as to where each -SV was originally allocated. This information is also displayed by -Devel::Peek. Note that the extra details recorded with each SV increases -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>, both memory and SV allocations go -through logging functions, which is handy for breakpoint setting. - -Unless C<-DPERL_MEM_LOG_NOIMPL> is also compiled, the logging -functions read $ENV{PERL_MEM_LOG} to determine whether to log the -event, and if so how: - - $ENV{PERL_MEM_LOG} =~ /m/ Log all memory ops - $ENV{PERL_MEM_LOG} =~ /s/ Log all SV ops - $ENV{PERL_MEM_LOG} =~ /t/ include timestamp in Log - $ENV{PERL_MEM_LOG} =~ /^(\d+)/ write to FD given (default is 2) - -Memory logging is somewhat similar to C<-Dm> but is independent of -C<-DDEBUGGING>, and at a higher level; all uses of Newx(), Renew(), -and Safefree() are logged with the caller's source code file and line -number (and C function name, if supported by the C compiler). In -contrast, C<-Dm> is directly at the point of C<malloc()>. SV logging -is similar. - -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. - -=head2 Profiling - -Depending on your platform there are various of profiling Perl. - -There are two commonly used techniques of profiling executables: -I<statistical time-sampling> and I<basic-block counting>. - -The first method takes periodically samples of the CPU program -counter, and since the program counter can be correlated with the code -generated for functions, we get a statistical view of in which -functions the program is spending its time. The caveats are that very -small/fast functions have lower probability of showing up in the -profile, and that periodically interrupting the program (this is -usually done rather frequently, in the scale of milliseconds) imposes -an additional overhead that may skew the results. The first problem -can be alleviated by running the code for longer (in general this is a -good idea for profiling), the second problem is usually kept in guard -by the profiling tools themselves. - -The second method divides up the generated code into I<basic blocks>. -Basic blocks are sections of code that are entered only in the -beginning and exited only at the end. For example, a conditional jump -starts a basic block. Basic block profiling usually works by -I<instrumenting> the code by adding I<enter basic block #nnnn> -book-keeping code to the generated code. During the execution of the -code the basic block counters are then updated appropriately. The -caveat is that the added extra code can skew the results: again, the -profiling tools usually try to factor their own effects out of the -results. - -=head2 Gprof Profiling - -gprof is a profiling tool available in many Unix platforms, -it uses F<statistical time-sampling>. - -You can build a profiled version of perl called "perl.gprof" by -invoking the make target "perl.gprof" (What is required is that Perl -must be compiled using the C<-pg> flag, you may need to re-Configure). -Running the profiled version of Perl will create an output file called -F<gmon.out> is created which contains the profiling data collected -during the execution. - -The gprof tool can then display the collected data in various ways. -Usually gprof understands the following options: +To hack on the Perl guts, you'll need to read the following things: =over 4 -=item -a - -Suppress statically defined functions from the profile. - -=item -b - -Suppress the verbose descriptions in the profile. - -=item -e routine - -Exclude the given routine and its descendants from the profile. - -=item -f routine - -Display only the given routine and its descendants in the profile. - -=item -s - -Generate a summary file called F<gmon.sum> which then may be given -to subsequent gprof runs to accumulate data over several runs. +=item * L<perlsource> -=item -z +An overview of the Perl source tree. This will help you find the files +you're looking for. -Display routines that have zero usage. +=item * L<perlinterp> -=back - -For more detailed explanation of the available commands and output -formats, see your own local documentation of gprof. - -quick hint: - - $ sh Configure -des -Dusedevel -Doptimize='-pg' && make perl.gprof - $ ./perl.gprof someprog # creates gmon.out in current directory - $ gprof ./perl.gprof > out - $ view out - -=head2 GCC gcov Profiling - -Starting from GCC 3.0 I<basic block profiling> is officially available -for the GNU CC. - -You can build a profiled version of perl called F<perl.gcov> by -invoking the make target "perl.gcov" (what is required that Perl must -be compiled using gcc with the flags C<-fprofile-arcs --ftest-coverage>, you may need to re-Configure). - -Running the profiled version of Perl will cause profile output to be -generated. For each source file an accompanying ".da" file will be -created. - -To display the results you use the "gcov" utility (which should -be installed if you have gcc 3.0 or newer installed). F<gcov> is -run on source code files, like this +An overview of the Perl interpreter source code and some details on how +Perl does what it does. - gcov sv.c +=item * L<perlhacktut> -which will cause F<sv.c.gcov> to be created. The F<.gcov> files -contain the source code annotated with relative frequencies of -execution indicated by "#" markers. +This document walks through the creation of a small patch to Perl's C +code. If you're just getting started with Perl core hacking, this will +help you understand how it works. -Useful options of F<gcov> include C<-b> which will summarise the -basic block, branch, and function call coverage, and C<-c> which -instead of relative frequencies will use the actual counts. For -more information on the use of F<gcov> and basic block profiling -with gcc, see the latest GNU CC manual, as of GCC 3.0 see +=item * L<perlhacktips> - http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc.html +More details on hacking the Perl core. This document focuses on lower +level details such as how to write tests, compilation issues, +portability, debugging, etc. -and its section titled "8. gcov: a Test Coverage Program" +If you plan on doing serious C hacking, make sure to read this. - http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc_8.html#SEC132 +=item * L<perlguts> -quick hint: - - $ sh Configure -des -Doptimize='-g' -Accflags='-fprofile-arcs -ftest-coverage' \ - -Aldflags='-fprofile-arcs -ftest-coverage' && make perl.gcov - $ rm -f regexec.c.gcov regexec.gcda - $ ./perl.gcov - $ gcov regexec.c - $ view regexec.c.gcov - -=head2 Pixie Profiling +This is of paramount importance, since it's the documentation of what +goes where in the Perl source. Read it over a couple of times and it +might start to make sense - don't worry if it doesn't yet, because the +best way to study it is to read it in conjunction with poking at Perl +source, and we'll do that later on. -Pixie is a profiling tool available on IRIX and Tru64 (aka Digital -UNIX aka DEC OSF/1) platforms. Pixie does its profiling using -I<basic-block counting>. +Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very +helpful pictures: -You can build a profiled version of perl called F<perl.pixie> by -invoking the make target "perl.pixie" (what is required is that Perl -must be compiled using the C<-g> flag, you may need to re-Configure). +L<http://search.cpan.org/dist/illguts/> -In Tru64 a file called F<perl.Addrs> will also be silently created, -this file contains the addresses of the basic blocks. Running the -profiled version of Perl will create a new file called "perl.Counts" -which contains the counts for the basic block for that particular -program execution. +=item * L<perlxstut> and L<perlxs> -To display the results you use the F<prof> utility. The exact -incantation depends on your operating system, "prof perl.Counts" in -IRIX, and "prof -pixie -all -L. perl" in Tru64. +A working knowledge of XSUB programming is incredibly useful for core +hacking; XSUBs use techniques drawn from the PP code, the portion of +the guts that actually executes a Perl program. It's a lot gentler to +learn those techniques from simple examples and explanation than from +the core itself. -In IRIX the following prof options are available: +=item * L<perlapi> -=over 4 +The documentation for the Perl API explains what some of the internal +functions do, as well as the many macros used in the source. -=item -h +=item * F<Porting/pumpkin.pod> -Reports the most heavily used lines in descending order of use. -Useful for finding the hotspot lines. +This is a collection of words of wisdom for a Perl porter; some of it +is only useful to the pumpkin holder, but most of it applies to anyone +wanting to go about Perl development. -=item -l +=item * The perl5-porters FAQ -Groups lines by procedure, with procedures sorted in descending order of use. -Within a procedure, lines are listed in source order. -Useful for finding the hotspots of procedures. +This should be available from +http://dev.perl.org/perl5/docs/p5p-faq.html . It contains hints on +reading perl5-porters, information on how perl5-porters works and how +Perl development in general works. =back -In Tru64 the following options are available: - -=over 4 - -=item -p[rocedures] - -Procedures sorted in descending order by the number of cycles executed -in each procedure. Useful for finding the hotspot procedures. -(This is the default option.) - -=item -h[eavy] - -Lines sorted in descending order by the number of cycles executed in -each line. Useful for finding the hotspot lines. - -=item -i[nvocations] - -The called procedures are sorted in descending order by number of calls -made to the procedures. Useful for finding the most used procedures. - -=item -l[ines] - -Grouped by procedure, sorted by cycles executed per procedure. -Useful for finding the hotspots of procedures. +=head1 CPAN TESTERS AND PERL SMOKERS -=item -testcoverage +The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers +who test CPAN modules on a variety of platforms. -The compiler emitted code for these lines, but the code was unexecuted. - -=item -z[ero] +Perl Smokers ( http://www.nntp.perl.org/group/perl.daily-build/ and +http://www.nntp.perl.org/group/perl.daily-build.reports/ ) +automatically test Perl source releases on platforms with various +configurations. + +Both efforts welcome volunteers. In order to get involved in smoke +testing of the perl itself visit +L<http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke +testing CPAN modules visit +L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or +L<http://search.cpan.org/dist/minismokebox/> or +L<http://search.cpan.org/dist/CPAN-Reporter/>. -Unexecuted procedures. +=head1 WHAT NEXT? -=back +If you've read all the documentation in the document and the ones +listed above, you're more than ready to hack on Perl. -For further information, see your system's manual pages for pixie and prof. - -=head2 Miscellaneous tricks +Here's some more recommendations =over 4 =item * -Those debugging perl with the DDD frontend over gdb may find the -following useful: - -You can extend the data conversion shortcuts menu, so for example you -can display an SV's IV value with one click, without doing any typing. -To do that simply edit ~/.ddd/init file and add after: - - ! Display shortcuts. - Ddd*gdbDisplayShortcuts: \ - /t () // Convert to Bin\n\ - /d () // Convert to Dec\n\ - /x () // Convert to Hex\n\ - /o () // Convert to Oct(\n\ - -the following two lines: - - ((XPV*) (())->sv_any )->xpv_pv // 2pvx\n\ - ((XPVIV*) (())->sv_any )->xiv_iv // 2ivx - -so now you can do ivx and pvx lookups or you can plug there the -sv_peek "conversion": - - Perl_sv_peek(my_perl, (SV*)()) // sv_peek - -(The my_perl is for threaded builds.) -Just remember that every line, but the last one, should end with \n\ - -Alternatively edit the init file interactively via: -3rd mouse button -> New Display -> Edit Menu - -Note: you can define up to 20 conversion shortcuts in the gdb -section. - -=item * - -If you see in a debugger a memory area mysteriously full of 0xABABABAB -or 0xEFEFEFEF, you may be seeing the effect of the Poison() macros, -see L<perlclib>. - -=item * - -Under ithreads the optree is read only. If you want to enforce this, to check -for write accesses from buggy code, compile with C<-DPL_OP_SLAB_ALLOC> to -enable the OP slab allocator and C<-DPERL_DEBUG_READONLY_OPS> to enable code -that allocates op memory via C<mmap>, and sets it read-only at run time. -Any write access to an op results in a C<SIGBUS> and abort. - -This code is intended for development only, and may not be portable even to -all Unix variants. Also, it is an 80% solution, in that it isn't able to make -all ops read only. Specifically it - -=over - -=item 1 - -Only sets read-only on all slabs of ops at C<CHECK> time, hence ops allocated -later via C<require> or C<eval> will be re-write - -=item 2 - -Turns an entire slab of ops read-write if the refcount of any op in the slab -needs to be decreased. - -=item 3 - -Turns an entire slab of ops read-write if any op from the slab is freed. - -=back - -It's not possible to turn the slabs to read-only after an action requiring -read-write access, as either can happen during op tree building time, so -there may still be legitimate write access. - -However, as an 80% solution it is still effective, as currently it catches -a write access during the generation of F<Config.pm>, which means that we -can't yet build F<perl> with this enabled. - -=back - - -=head1 CONCLUSION - -We've had a brief look around the Perl source, how to maintain quality -of the source code, an overview of the stages F<perl> goes through -when it's running your code, how to use debuggers to poke at the Perl -guts, and finally how to analyse the execution of Perl. We took a very -simple problem and demonstrated how to solve it fully - with -documentation, regression tests, and finally a patch for submission to -p5p. Finally, we talked about how to use external tools to debug and -test Perl. - -I'd now suggest you read over those references again, and then, as soon -as possible, get your hands dirty. The best way to learn is by doing, -so: - -=over 3 - -=item * - Subscribe to perl5-porters, follow the patches and try and understand them; don't be afraid to ask if there's a portion you're not clear on - who knows, you may unearth a bug in the patch... =item * -Keep up to date with the bleeding edge Perl distributions and get -familiar with the changes. Try and get an idea of what areas people are -working on and the changes they're making. - -=item * - -Do read the README associated with your operating system, e.g. README.aix -on the IBM AIX OS. Don't hesitate to supply patches to that README if -you find anything missing or changed over a new OS release. +Do read the README associated with your operating system, e.g. +README.aix on the IBM AIX OS. Don't hesitate to supply patches to that +README if you find anything missing or changed over a new OS release. =item * Find an area of Perl that seems interesting to you, and see if you can work out how it works. Scan through the source, and step over it in the debugger. Play, poke, investigate, fiddle! You'll probably get to -understand not just your chosen area but a much wider range of F<perl>'s -activity as well, and probably sooner than you'd think. +understand not just your chosen area but a much wider range of +F<perl>'s activity as well, and probably sooner than you'd think. =back -=over 3 - -=item I<The Road goes ever on and on, down from the door where it began.> +=head2 "The Road goes ever on and on, down from the door where it began." -=back - -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! +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. +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. +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 +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 * +=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. +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. +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. +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. +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. +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 +This document was originally written by Nathan Torkington, and is +maintained by the perl5-porters mailing list. -L<perlrepository> diff --git a/Master/tlpkg/tlperl/lib/pods/perlhacktips.pod b/Master/tlpkg/tlperl/lib/pods/perlhacktips.pod new file mode 100644 index 00000000000..943ad4631b8 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perlhacktips.pod @@ -0,0 +1,1459 @@ +=encoding utf8 + +=for comment +Consistent formatting of this file is achieved with: + perl ./Porting/podtidy pod/perlhacktips.pod + +=head1 NAME + +perlhacktips - Tips for Perl core C code hacking + +=head1 DESCRIPTION + +This document will help you learn the best way to go about hacking on +the Perl core C code. It covers common problems, debugging, profiling, +and more. + +If you haven't read L<perlhack> and L<perlhacktut> yet, you might want +to do that first. + +=head1 COMMON PROBLEMS + +Perl source plays by ANSI C89 rules: no C99 (or C++) extensions. In +some cases we have to take pre-ANSI requirements into consideration. +You don't care about some particular platform having broken Perl? I +hear there is still a strong demand for J2EE programmers. + +=head2 Perl environment problems + +=over 4 + +=item * + +Not compiling with threading + +Compiling with threading (-Duseithreads) completely rewrites the +function prototypes of Perl. You better try your changes with that. +Related to this is the difference between "Perl_-less" and "Perl_-ly" +APIs, for example: + + Perl_sv_setiv(aTHX_ ...); + sv_setiv(...); + +The first one explicitly passes in the context, which is needed for +e.g. threaded builds. The second one does that implicitly; do not get +them mixed. If you are not passing in a aTHX_, you will need to do a +dTHX (or a dVAR) as the first thing in the function. + +See L<perlguts/"How multiple interpreters and concurrency are +supported"> for further discussion about context. + +=item * + +Not compiling with -DDEBUGGING + +The DEBUGGING define exposes more code to the compiler, therefore more +ways for things to go wrong. You should try it. + +=item * + +Introducing (non-read-only) globals + +Do not introduce any modifiable globals, truly global or file static. +They are bad form and complicate multithreading and other forms of +concurrency. The right way is to introduce them as new interpreter +variables, see F<intrpvar.h> (at the very end for binary +compatibility). + +Introducing read-only (const) globals is okay, as long as you verify +with e.g. C<nm libperl.a|egrep -v ' [TURtr] '> (if your C<nm> has +BSD-style output) that the data you added really is read-only. (If it +is, it shouldn't show up in the output of that command.) + +If you want to have static strings, make them constant: + + static const char etc[] = "..."; + +If you want to have arrays of constant strings, note carefully the +right combination of C<const>s: + + static const char * const yippee[] = + {"hi", "ho", "silver"}; + +There is a way to completely hide any modifiable globals (they are all +moved to heap), the compilation setting +C<-DPERL_GLOBAL_STRUCT_PRIVATE>. It is not normally used, but can be +used for testing, read more about it in L<perlguts/"Background and +PERL_IMPLICIT_CONTEXT">. + +=item * + +Not exporting your new function + +Some platforms (Win32, AIX, VMS, OS/2, to name a few) require any +function that is part of the public API (the shared Perl library) to be +explicitly marked as exported. See the discussion about F<embed.pl> in +L<perlguts>. + +=item * + +Exporting your new function + +The new shiny result of either genuine new functionality or your +arduous refactoring is now ready and correctly exported. So what could +possibly go wrong? + +Maybe simply that your function did not need to be exported in the +first place. Perl has a long and not so glorious history of exporting +functions that it should not have. + +If the function is used only inside one source code file, make it +static. See the discussion about F<embed.pl> in L<perlguts>. + +If the function is used across several files, but intended only for +Perl's internal use (and this should be the common case), do not export +it to the public API. See the discussion about F<embed.pl> in +L<perlguts>. + +=back + +=head2 Portability problems + +The following are common causes of compilation and/or execution +failures, not common to Perl as such. The C FAQ is good bedtime +reading. Please test your changes with as many C compilers and +platforms as possible; we will, anyway, and it's nice to save oneself +from public embarrassment. + +If using gcc, you can add the C<-std=c89> option which will hopefully +catch most of these unportabilities. (However it might also catch +incompatibilities in your system's header files.) + +Use the Configure C<-Dgccansipedantic> flag to enable the gcc C<-ansi +-pedantic> flags which enforce stricter ANSI rules. + +If using the C<gcc -Wall> note that not all the possible warnings (like +C<-Wunitialized>) are given unless you also compile with C<-O>. + +Note that if using gcc, starting from Perl 5.9.5 the Perl core source +code files (the ones at the top level of the source code distribution, +but not e.g. the extensions under ext/) are automatically compiled with +as many as possible of the C<-std=c89>, C<-ansi>, C<-pedantic>, and a +selection of C<-W> flags (see cflags.SH). + +Also study L<perlport> carefully to avoid any bad assumptions about the +operating system, filesystems, and so forth. + +You may once in a while try a "make microperl" to see whether we can +still compile Perl with just the bare minimum of interfaces. (See +README.micro.) + +Do not assume an operating system indicates a certain compiler. + +=over 4 + +=item * + +Casting pointers to integers or casting integers to pointers + + void castaway(U8* p) + { + IV i = p; + +or + + void castaway(U8* p) + { + IV i = (IV)p; + +Both are bad, and broken, and unportable. Use the PTR2IV() macro that +does it right. (Likewise, there are PTR2UV(), PTR2NV(), INT2PTR(), and +NUM2PTR().) + +=item * + +Casting between data function pointers and data pointers + +Technically speaking casting between function pointers and data +pointers is unportable and undefined, but practically speaking it seems +to work, but you should use the FPTR2DPTR() and DPTR2FPTR() macros. +Sometimes you can also play games with unions. + +=item * + +Assuming sizeof(int) == sizeof(long) + +There are platforms where longs are 64 bits, and platforms where ints +are 64 bits, and while we are out to shock you, even platforms where +shorts are 64 bits. This is all legal according to the C standard. (In +other words, "long long" is not a portable way to specify 64 bits, and +"long long" is not even guaranteed to be any wider than "long".) + +Instead, use the definitions IV, UV, IVSIZE, I32SIZE, and so forth. +Avoid things like I32 because they are B<not> guaranteed to be +I<exactly> 32 bits, they are I<at least> 32 bits, nor are they +guaranteed to be B<int> or B<long>. If you really explicitly need +64-bit variables, use I64 and U64, but only if guarded by HAS_QUAD. + +=item * + +Assuming one can dereference any type of pointer for any type of data + + char *p = ...; + long pony = *p; /* BAD */ + +Many platforms, quite rightly so, will give you a core dump instead of +a pony if the p happens not be correctly aligned. + +=item * + +Lvalue casts + + (int)*p = ...; /* BAD */ + +Simply not portable. Get your lvalue to be of the right type, or maybe +use temporary variables, or dirty tricks with unions. + +=item * + +Assume B<anything> about structs (especially the ones you don't +control, like the ones coming from the system headers) + +=over 8 + +=item * + +That a certain field exists in a struct + +=item * + +That no other fields exist besides the ones you know of + +=item * + +That a field is of certain signedness, sizeof, or type + +=item * + +That the fields are in a certain order + +=over 8 + +=item * + +While C guarantees the ordering specified in the struct definition, +between different platforms the definitions might differ + +=back + +=item * + +That the sizeof(struct) or the alignments are the same everywhere + +=over 8 + +=item * + +There might be padding bytes between the fields to align the fields - +the bytes can be anything + +=item * + +Structs are required to be aligned to the maximum alignment required by +the fields - which for native types is for usually equivalent to +sizeof() of the field + +=back + +=back + +=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 being changed +starting 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) ... \ + #ifdef BURGLE_OLD_STYLE /* BAD */ + ... do it the old way ... \ + #else + ... do it the new way ... \ + #endif + +You cannot portably "stack" cpp directives. For example in the above +you need two separate BURGLE() #defines, one for each #ifdef branch. + +=item * + +Adding non-comment stuff after #endif or #else + + #ifdef SNOSH + ... + #else !SNOSH /* BAD */ + ... + #endif SNOSH /* BAD */ + +The #endif and #else cannot portably have anything non-comment after +them. If you want to document what is going (which is a good idea +especially if the branches are long), use (C) comments: + + #ifdef SNOSH + ... + #else /* !SNOSH */ + ... + #endif /* SNOSH */ + +The gcc option C<-Wendif-labels> warns about the bad variant (by +default on starting from Perl 5.9.4). + +=item * + +Having a comma after the last element of an enum list + + enum color { + CERULEAN, + CHARTREUSE, + CINNABAR, /* BAD */ + }; + +is not portable. Leave out the last comma. + +Also note that whether enums are implicitly morphable to ints varies +between compilers, you might need to (int). + +=item * + +Using //-comments + + // This function bamfoodles the zorklator. /* BAD */ + +That is C99 or C++. Perl is C89. Using the //-comments is silently +allowed by many C compilers but cranking up the ANSI C89 strictness +(which we like to do) causes the compilation to fail. + +=item * + +Mixing declarations and code + + void zorklator() + { + int n = 3; + set_zorkmids(n); /* BAD */ + int q = 4; + +That is C99 or C++. Some C compilers allow that, but you shouldn't. + +The gcc option C<-Wdeclaration-after-statements> scans for such +problems (by default on starting from Perl 5.9.4). + +=item * + +Introducing variables inside for() + + for(int i = ...; ...; ...) { /* BAD */ + +That is C99 or C++. While it would indeed be awfully nice to have that +also in C89, to limit the scope of the loop variable, alas, we cannot. + +=item * + +Mixing signed char pointers with unsigned char pointers + + int foo(char *s) { ... } + ... + unsigned char *t = ...; /* Or U8* t = ... */ + foo(t); /* BAD */ + +While this is legal practice, it is certainly dubious, and downright +fatal in at least one platform: for example VMS cc considers this a +fatal error. One cause for people often making this mistake is that a +"naked char" and therefore dereferencing a "naked char pointer" have an +undefined signedness: it depends on the compiler and the flags of the +compiler and the underlying platform whether the result is signed or +unsigned. For this very same reason using a 'char' as an array index is +bad. + +=item * + +Macros that have string constants and their arguments as substrings of +the string constants + + #define FOO(n) printf("number = %d\n", n) /* BAD */ + FOO(10); + +Pre-ANSI semantics for that was equivalent to + + printf("10umber = %d\10"); + +which is probably not what you were expecting. Unfortunately at least +one reasonably common and modern C compiler does "real backward +compatibility" here, in AIX that is what still happens even though the +rest of the AIX compiler is very happily C89. + +=item * + +Using printf formats for non-basic C types + + IV i = ...; + printf("i = %d\n", i); /* BAD */ + +While this might by accident work in some platform (where IV happens to +be an C<int>), in general it cannot. IV might be something larger. Even +worse the situation is with more specific types (defined by Perl's +configuration step in F<config.h>): + + Uid_t who = ...; + printf("who = %d\n", who); /* BAD */ + +The problem here is that Uid_t might be not only not C<int>-wide but it +might also be unsigned, in which case large uids would be printed as +negative values. + +There is no simple solution to this because of printf()'s limited +intelligence, but for many types the right format is available as with +either 'f' or '_f' suffix, for example: + + IVdf /* IV in decimal */ + UVxf /* UV is hexadecimal */ + + printf("i = %"IVdf"\n", i); /* The IVdf is a string constant. */ + + Uid_t_f /* Uid_t in decimal */ + + printf("who = %"Uid_t_f"\n", who); + +Or you can try casting to a "wide enough" type: + + printf("i = %"IVdf"\n", (IV)something_very_small_and_signed); + +Also remember that the C<%p> format really does require a void pointer: + + U8* p = ...; + printf("p = %p\n", (void*)p); + +The gcc option C<-Wformat> scans for such problems. + +=item * + +Blindly using variadic macros + +gcc has had them for a while with its own syntax, and C99 brought them +with a standardized syntax. Don't use the former, and use the latter +only if the HAS_C99_VARIADIC_MACROS is defined. + +=item * + +Blindly passing va_list + +Not all platforms support passing va_list to further varargs (stdarg) +functions. The right thing to do is to copy the va_list using the +Perl_va_copy() if the NEED_VA_COPY is defined. + +=item * + +Using gcc statement expressions + + val = ({...;...;...}); /* BAD */ + +While a nice extension, it's not portable. The Perl code does +admittedly use them if available to gain some extra speed (essentially +as a funky form of inlining), but you shouldn't. + +=item * + +Binding together several statements in a macro + +Use the macros STMT_START and STMT_END. + + STMT_START { + ... + } STMT_END + +=item * + +Testing for operating systems or versions when should be testing for +features + + #ifdef __FOONIX__ /* BAD */ + foo = quux(); + #endif + +Unless you know with 100% certainty that quux() is only ever available +for the "Foonix" operating system B<and> that is available B<and> +correctly working for B<all> past, present, B<and> future versions of +"Foonix", the above is very wrong. This is more correct (though still +not perfect, because the below is a compile-time check): + + #ifdef HAS_QUUX + foo = quux(); + #endif + +How does the HAS_QUUX become defined where it needs to be? Well, if +Foonix happens to be Unixy enough to be able to run the Configure +script, and Configure has been taught about detecting and testing +quux(), the HAS_QUUX will be correctly defined. In other platforms, the +corresponding configuration step will hopefully do the same. + +In a pinch, if you cannot wait for Configure to be educated, or if you +have a good hunch of where quux() might be available, you can +temporarily try the following: + + #if (defined(__FOONIX__) || defined(__BARNIX__)) + # define HAS_QUUX + #endif + + ... + + #ifdef HAS_QUUX + foo = quux(); + #endif + +But in any case, try to keep the features and operating systems +separate. + +=back + +=head2 Problematic System Interfaces + +=over 4 + +=item * + +malloc(0), realloc(0), calloc(0, 0) are non-portable. To be portable +allocate at least one byte. (In general you should rarely need to work +at this low level, but instead use the various malloc wrappers.) + +=item * + +snprintf() - the return type is unportable. Use my_snprintf() instead. + +=back + +=head2 Security problems + +Last but not least, here are various tips for safer coding. + +=over 4 + +=item * + +Do not use gets() + +Or we will publicly ridicule you. Seriously. + +=item * + +Do not use strcpy() or strcat() or strncpy() or strncat() + +Use my_strlcpy() and my_strlcat() instead: they either use the native +implementation, or Perl's own implementation (borrowed from the public +domain implementation of INN). + +=item * + +Do not use sprintf() or vsprintf() + +If you really want just plain byte strings, use my_snprintf() and +my_vsnprintf() instead, which will try to use snprintf() and +vsnprintf() if those safer APIs are available. If you want something +fancier than a plain byte string, use SVs and Perl_sv_catpvf(). + +=back + +=head1 DEBUGGING + +You can compile a special debugging version of Perl, which allows you +to use the C<-D> option of Perl to tell more about what Perl is doing. +But sometimes there is no alternative than to dive in with a debugger, +either to see the stack trace of a core dump (very useful in a bug +report), or trying to figure out what went wrong before the core dump +happened, or how did we end up having wrong or unexpected results. + +=head2 Poking at Perl + +To really poke around with Perl, you'll probably want to build Perl for +debugging, like this: + + ./Configure -d -D optimize=-g + make + +C<-g> is a flag to the C compiler to have it produce debugging +information which will allow us to step through a running program, and +to see in which C function we are at (without the debugging information +we might see only the numerical addresses of the functions, which is +not very helpful). + +F<Configure> will also turn on the C<DEBUGGING> compilation symbol +which enables all the internal debugging code in Perl. There are a +whole bunch of things you can debug with this: L<perlrun> lists them +all, and the best way to find out about them is to play about with +them. The most useful options are probably + + l Context (loop) stack processing + t Trace execution + o Method and overloading resolution + c String/numeric conversions + +Some of the functionality of the debugging code can be achieved using +XS modules. + + -Dr => use re 'debug' + -Dx => use O 'Debug' + +=head2 Using a source-level debugger + +If the debugging output of C<-D> doesn't help you, it's time to step +through perl's execution with a source-level debugger. + +=over 3 + +=item * + +We'll use C<gdb> for our examples here; the principles will apply to +any debugger (many vendors call their debugger C<dbx>), but check the +manual of the one you're using. + +=back + +To fire up the debugger, type + + gdb ./perl + +Or if you have a core dump: + + gdb ./perl core + +You'll want to do that in your Perl source tree so the debugger can +read the source code. You should see the copyright message, followed by +the prompt. + + (gdb) + +C<help> will get you into the documentation, but here are the most +useful commands: + +=over 3 + +=item * run [args] + +Run the program with the given arguments. + +=item * break function_name + +=item * break source.c:xxx + +Tells the debugger that we'll want to pause execution when we reach +either the named function (but see L<perlguts/Internal Functions>!) or +the given line in the named source file. + +=item * step + +Steps through the program a line at a time. + +=item * next + +Steps through the program a line at a time, without descending into +functions. + +=item * continue + +Run until the next breakpoint. + +=item * finish + +Run until the end of the current function, then stop again. + +=item * 'enter' + +Just pressing Enter will do the most recent operation again - it's a +blessing when stepping through miles of source code. + +=item * print + +Execute the given C code and print its results. B<WARNING>: Perl makes +heavy use of macros, and F<gdb> does not necessarily support macros +(see later L</"gdb macro support">). You'll have to substitute them +yourself, or to invoke cpp on the source code files (see L</"The .i +Targets">) So, for instance, you can't say + + print SvPV_nolen(sv) + +but you have to say + + print Perl_sv_2pv_nolen(sv) + +=back + +You may find it helpful to have a "macro dictionary", which you can +produce by saying C<cpp -dM perl.c | sort>. Even then, F<cpp> won't +recursively apply those macros for you. + +=head2 gdb macro support + +Recent versions of F<gdb> have fairly good macro support, but in order +to use it you'll need to compile perl with macro definitions included +in the debugging information. Using F<gcc> version 3.1, this means +configuring with C<-Doptimize=-g3>. Other compilers might use a +different switch (if they support debugging macros at all). + +=head2 Dumping Perl Data Structures + +One way to get around this macro hell is to use the dumping functions +in F<dump.c>; these work a little like an internal +L<Devel::Peek|Devel::Peek>, but they also cover OPs and other +structures that you can't get at from Perl. Let's take an example. +We'll use the C<$a = $b + $c> we used before, but give it a bit of +context: C<$b = "6XXXX"; $c = 2.3;>. Where's a good place to stop and +poke around? + +What about C<pp_add>, the function we examined earlier to implement the +C<+> operator: + + (gdb) break Perl_pp_add + Breakpoint 1 at 0x46249f: file pp_hot.c, line 309. + +Notice we use C<Perl_pp_add> and not C<pp_add> - see +L<perlguts/Internal Functions>. With the breakpoint in place, we can +run our program: + + (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c' + +Lots of junk will go past as gdb reads in the relevant source files and +libraries, and then: + + Breakpoint 1, Perl_pp_add () at pp_hot.c:309 + 309 dSP; dATARGET; tryAMAGICbin(add,opASSIGN); + (gdb) step + 311 dPOPTOPnnrl_ul; + (gdb) + +We looked at this bit of code before, and we said that +C<dPOPTOPnnrl_ul> arranges for two C<NV>s to be placed into C<left> and +C<right> - let's slightly expand it: + + #define dPOPTOPnnrl_ul NV right = POPn; \ + SV *leftsv = TOPs; \ + NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0 + +C<POPn> takes the SV from the top of the stack and obtains its NV +either directly (if C<SvNOK> is set) or by calling the C<sv_2nv> +function. C<TOPs> takes the next SV from the top of the stack - yes, +C<POPn> uses C<TOPs> - but doesn't remove it. We then use C<SvNV> to +get the NV from C<leftsv> in the same way as before - yes, C<POPn> uses +C<SvNV>. + +Since we don't have an NV for C<$b>, we'll have to use C<sv_2nv> to +convert it. If we step again, we'll find ourselves there: + + Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669 + 1669 if (!sv) + (gdb) + +We can now use C<Perl_sv_dump> to investigate the SV: + + SV = PV(0xa057cc0) at 0xa0675d0 + REFCNT = 1 + FLAGS = (POK,pPOK) + PV = 0xa06a510 "6XXXX"\0 + CUR = 5 + LEN = 6 + $1 = void + +We know we're going to get C<6> from this, so let's finish the +subroutine: + + (gdb) finish + Run till exit from #0 Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671 + 0x462669 in Perl_pp_add () at pp_hot.c:311 + 311 dPOPTOPnnrl_ul; + +We can also dump out this op: the current op is always stored in +C<PL_op>, and we can dump it with C<Perl_op_dump>. This'll give us +similar output to L<B::Debug|B::Debug>. + + { + 13 TYPE = add ===> 14 + TARG = 1 + FLAGS = (SCALAR,KIDS) + { + TYPE = null ===> (12) + (was rv2sv) + FLAGS = (SCALAR,KIDS) + { + 11 TYPE = gvsv ===> 12 + FLAGS = (SCALAR) + GV = main::b + } + } + +# finish this later # + +=head1 SOURCE CODE STATIC ANALYSIS + +Various tools exist for analysing C source code B<statically>, as +opposed to B<dynamically>, that is, without executing the code. It is +possible to detect resource leaks, undefined behaviour, type +mismatches, portability problems, code paths that would cause illegal +memory accesses, and other similar problems by just parsing the C code +and looking at the resulting graph, what does it tell about the +execution and data flows. As a matter of fact, this is exactly how C +compilers know to give warnings about dubious code. + +=head2 lint, splint + +The good old C code quality inspector, C<lint>, is available in several +platforms, but please be aware that there are several different +implementations of it by different vendors, which means that the flags +are not identical across different platforms. + +There is a lint variant called C<splint> (Secure Programming Lint) +available from http://www.splint.org/ that should compile on any +Unix-like platform. + +There are C<lint> and <splint> targets in Makefile, but you may have to +diddle with the flags (see above). + +=head2 Coverity + +Coverity (http://www.coverity.com/) is a product similar to lint and as +a testbed for their product they periodically check several open source +projects, and they give out accounts to open source developers to the +defect databases. + +=head2 cpd (cut-and-paste detector) + +The cpd tool detects cut-and-paste coding. If one instance of the +cut-and-pasted code changes, all the other spots should probably be +changed, too. Therefore such code should probably be turned into a +subroutine or a macro. + +cpd (http://pmd.sourceforge.net/cpd.html) is part of the pmd project +(http://pmd.sourceforge.net/). pmd was originally written for static +analysis of Java code, but later the cpd part of it was extended to +parse also C and C++. + +Download the pmd-bin-X.Y.zip () from the SourceForge site, extract the +pmd-X.Y.jar from it, and then run that on source code thusly: + + java -cp pmd-X.Y.jar net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /some/where/src --language c > cpd.txt + +You may run into memory limits, in which case you should use the -Xmx +option: + + java -Xmx512M ... + +=head2 gcc warnings + +Though much can be written about the inconsistency and coverage +problems of gcc warnings (like C<-Wall> not meaning "all the warnings", +or some common portability problems not being covered by C<-Wall>, or +C<-ansi> and C<-pedantic> both being a poorly defined collection of +warnings, and so forth), gcc is still a useful tool in keeping our +coding nose clean. + +The C<-Wall> is by default on. + +The C<-ansi> (and its sidekick, C<-pedantic>) would be nice to be on +always, but unfortunately they are not safe on all platforms, they can +for example cause fatal conflicts with the system headers (Solaris +being a prime example). If Configure C<-Dgccansipedantic> is used, the +C<cflags> frontend selects C<-ansi -pedantic> for the platforms where +they are known to be safe. + +Starting from Perl 5.9.4 the following extra flags are added: + +=over 4 + +=item * + +C<-Wendif-labels> + +=item * + +C<-Wextra> + +=item * + +C<-Wdeclaration-after-statement> + +=back + +The following flags would be nice to have but they would first need +their own Augean stablemaster: + +=over 4 + +=item * + +C<-Wpointer-arith> + +=item * + +C<-Wshadow> + +=item * + +C<-Wstrict-prototypes> + +=back + +The C<-Wtraditional> is another example of the annoying tendency of gcc +to bundle a lot of warnings under one switch (it would be impossible to +deploy in practice because it would complain a lot) but it does contain +some warnings that would be beneficial to have available on their own, +such as the warning about string constants inside macros containing the +macro arguments: this behaved differently pre-ANSI than it does in +ANSI, and some C compilers are still in transition, AIX being an +example. + +=head2 Warnings of other C compilers + +Other C compilers (yes, there B<are> other C compilers than gcc) often +have their "strict ANSI" or "strict ANSI with some portability +extensions" modes on, like for example the Sun Workshop has its C<-Xa> +mode on (though implicitly), or the DEC (these days, HP...) has its +C<-std1> mode on. + +=head1 MEMORY DEBUGGERS + +B<NOTE 1>: Running under memory debuggers such as Purify, valgrind, or +Third Degree greatly slows down the execution: seconds become minutes, +minutes become hours. For example as of Perl 5.8.1, the +ext/Encode/t/Unicode.t takes extraordinarily long to complete under +e.g. Purify, Third Degree, and valgrind. Under valgrind it takes more +than six hours, even on a snappy computer. The said test must be doing +something that is quite unfriendly for memory debuggers. If you don't +feel like waiting, that you can simply kill away the perl process. + +B<NOTE 2>: To minimize the number of memory leak false alarms (see +L</PERL_DESTRUCT_LEVEL> for more information), you have to set the +environment variable PERL_DESTRUCT_LEVEL to 2. + +For csh-like shells: + + setenv PERL_DESTRUCT_LEVEL 2 + +For Bourne-type shells: + + PERL_DESTRUCT_LEVEL=2 + export PERL_DESTRUCT_LEVEL + +In Unixy environments you can also use the C<env> command: + + env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ... + +B<NOTE 3>: There are known memory leaks when there are compile-time +errors within eval or require, seeing C<S_doeval> in the call stack is +a good sign of these. Fixing these leaks is non-trivial, unfortunately, +but they must be fixed eventually. + +B<NOTE 4>: L<DynaLoader> will not clean up after itself completely +unless Perl is built with the Configure option +C<-Accflags=-DDL_UNLOAD_ALL_AT_EXIT>. + +=head2 Rational Software's Purify + +Purify is a commercial tool that is helpful in identifying memory +overruns, wild pointers, memory leaks and other such badness. Perl must +be compiled in a specific way for optimal testing with Purify. Purify +is available under Windows NT, Solaris, HP-UX, SGI, and Siemens Unix. + +=head3 Purify on Unix + +On Unix, Purify creates a new Perl binary. To get the most benefit out +of Purify, you should create the perl to Purify using: + + sh Configure -Accflags=-DPURIFY -Doptimize='-g' \ + -Uusemymalloc -Dusemultiplicity + +where these arguments mean: + +=over 4 + +=item * -Accflags=-DPURIFY + +Disables Perl's arena memory allocation functions, as well as forcing +use of memory allocation functions derived from the system malloc. + +=item * -Doptimize='-g' + +Adds debugging information so that you see the exact source statements +where the problem occurs. Without this flag, all you will see is the +source filename of where the error occurred. + +=item * -Uusemymalloc + +Disable Perl's malloc so that Purify can more closely monitor +allocations and leaks. Using Perl's malloc will make Purify report most +leaks in the "potential" leaks category. + +=item * -Dusemultiplicity + +Enabling the multiplicity option allows perl to clean up thoroughly +when the interpreter shuts down, which reduces the number of bogus leak +reports from Purify. + +=back + +Once you've compiled a perl suitable for Purify'ing, then you can just: + + make pureperl + +which creates a binary named 'pureperl' that has been Purify'ed. This +binary is used in place of the standard 'perl' binary when you want to +debug Perl memory problems. + +As an example, to show any memory leaks produced during the standard +Perl testset you would create and run the Purify'ed perl as: + + make pureperl + cd t + ../pureperl -I../lib harness + +which would run Perl on test.pl and report any memory problems. + +Purify outputs messages in "Viewer" windows by default. If you don't +have a windowing environment or if you simply want the Purify output to +unobtrusively go to a log file instead of to the interactive window, +use these following options to output to the log file "perl.log": + + setenv PURIFYOPTIONS "-chain-length=25 -windows=no \ + -log-file=perl.log -append-logfile=yes" + +If you plan to use the "Viewer" windows, then you only need this +option: + + setenv PURIFYOPTIONS "-chain-length=25" + +In Bourne-type shells: + + PURIFYOPTIONS="..." + export PURIFYOPTIONS + +or if you have the "env" utility: + + env PURIFYOPTIONS="..." ../pureperl ... + +=head3 Purify on NT + +Purify on Windows NT instruments the Perl binary 'perl.exe' on the fly. + There are several options in the makefile you should change to get the +most use out of Purify: + +=over 4 + +=item * DEFINES + +You should add -DPURIFY to the DEFINES line so the DEFINES line looks +something like: + + DEFINES = -DWIN32 -D_CONSOLE -DNO_STRICT $(CRYPT_FLAG) -DPURIFY=1 + +to disable Perl's arena memory allocation functions, as well as to +force use of memory allocation functions derived from the system +malloc. + +=item * USE_MULTI = define + +Enabling the multiplicity option allows perl to clean up thoroughly +when the interpreter shuts down, which reduces the number of bogus leak +reports from Purify. + +=item * #PERL_MALLOC = define + +Disable Perl's malloc so that Purify can more closely monitor +allocations and leaks. Using Perl's malloc will make Purify report most +leaks in the "potential" leaks category. + +=item * CFG = Debug + +Adds debugging information so that you see the exact source statements +where the problem occurs. Without this flag, all you will see is the +source filename of where the error occurred. + +=back + +As an example, to show any memory leaks produced during the standard +Perl testset you would create and run Purify as: + + cd win32 + make + cd ../t + purify ../perl -I../lib harness + +which would instrument Perl in memory, run Perl on test.pl, then +finally report any memory problems. + +=head2 valgrind + +The excellent valgrind tool can be used to find out both memory leaks +and illegal memory accesses. As of version 3.3.0, Valgrind only +supports Linux on x86, x86-64 and PowerPC. The special "test.valgrind" +target can be used to run the tests under valgrind. Found errors and +memory leaks are logged in files named F<testfile.valgrind>. + +Valgrind also provides a cachegrind tool, invoked on perl as: + + VG_OPTS=--tool=cachegrind make test.valgrind + +As system libraries (most notably glibc) are also triggering errors, +valgrind allows to suppress such errors using suppression files. The +default suppression file that comes with valgrind already catches a lot +of them. Some additional suppressions are defined in F<t/perl.supp>. + +To get valgrind and for more information see + + http://developer.kde.org/~sewardj/ + +=head1 PROFILING + +Depending on your platform there are various ways of profiling Perl. + +There are two commonly used techniques of profiling executables: +I<statistical time-sampling> and I<basic-block counting>. + +The first method takes periodically samples of the CPU program counter, +and since the program counter can be correlated with the code generated +for functions, we get a statistical view of in which functions the +program is spending its time. The caveats are that very small/fast +functions have lower probability of showing up in the profile, and that +periodically interrupting the program (this is usually done rather +frequently, in the scale of milliseconds) imposes an additional +overhead that may skew the results. The first problem can be alleviated +by running the code for longer (in general this is a good idea for +profiling), the second problem is usually kept in guard by the +profiling tools themselves. + +The second method divides up the generated code into I<basic blocks>. +Basic blocks are sections of code that are entered only in the +beginning and exited only at the end. For example, a conditional jump +starts a basic block. Basic block profiling usually works by +I<instrumenting> the code by adding I<enter basic block #nnnn> +book-keeping code to the generated code. During the execution of the +code the basic block counters are then updated appropriately. The +caveat is that the added extra code can skew the results: again, the +profiling tools usually try to factor their own effects out of the +results. + +=head2 Gprof Profiling + +gprof is a profiling tool available in many Unix platforms, it uses +F<statistical time-sampling>. + +You can build a profiled version of perl called "perl.gprof" by +invoking the make target "perl.gprof" (What is required is that Perl +must be compiled using the C<-pg> flag, you may need to re-Configure). +Running the profiled version of Perl will create an output file called +F<gmon.out> is created which contains the profiling data collected +during the execution. + +The gprof tool can then display the collected data in various ways. +Usually gprof understands the following options: + +=over 4 + +=item * -a + +Suppress statically defined functions from the profile. + +=item * -b + +Suppress the verbose descriptions in the profile. + +=item * -e routine + +Exclude the given routine and its descendants from the profile. + +=item * -f routine + +Display only the given routine and its descendants in the profile. + +=item * -s + +Generate a summary file called F<gmon.sum> which then may be given to +subsequent gprof runs to accumulate data over several runs. + +=item * -z + +Display routines that have zero usage. + +=back + +For more detailed explanation of the available commands and output +formats, see your own local documentation of gprof. + +quick hint: + + $ sh Configure -des -Dusedevel -Doptimize='-pg' && make perl.gprof + $ ./perl.gprof someprog # creates gmon.out in current directory + $ gprof ./perl.gprof > out + $ view out + +=head2 GCC gcov Profiling + +Starting from GCC 3.0 I<basic block profiling> is officially available +for the GNU CC. + +You can build a profiled version of perl called F<perl.gcov> by +invoking the make target "perl.gcov" (what is required that Perl must +be compiled using gcc with the flags C<-fprofile-arcs -ftest-coverage>, +you may need to re-Configure). + +Running the profiled version of Perl will cause profile output to be +generated. For each source file an accompanying ".da" file will be +created. + +To display the results you use the "gcov" utility (which should be +installed if you have gcc 3.0 or newer installed). F<gcov> is run on +source code files, like this + + gcov sv.c + +which will cause F<sv.c.gcov> to be created. The F<.gcov> files contain +the source code annotated with relative frequencies of execution +indicated by "#" markers. + +Useful options of F<gcov> include C<-b> which will summarise the basic +block, branch, and function call coverage, and C<-c> which instead of +relative frequencies will use the actual counts. For more information +on the use of F<gcov> and basic block profiling with gcc, see the +latest GNU CC manual, as of GCC 3.0 see + + http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc.html + +and its section titled "8. gcov: a Test Coverage Program" + + http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc_8.html#SEC132 + +quick hint: + + $ sh Configure -des -Dusedevel -Doptimize='-g' \ + -Accflags='-fprofile-arcs -ftest-coverage' \ + -Aldflags='-fprofile-arcs -ftest-coverage' && make perl.gcov + $ rm -f regexec.c.gcov regexec.gcda + $ ./perl.gcov + $ gcov regexec.c + $ view regexec.c.gcov + +=head1 MISCELLANEOUS TRICKS + +=head2 PERL_DESTRUCT_LEVEL + +If you want to run any of the tests yourself manually using e.g. +valgrind, or the pureperl or perl.third executables, please note that +by default perl B<does not> explicitly cleanup all the memory it has +allocated (such as global memory arenas) but instead lets the exit() of +the whole program "take care" of such allocations, also known as +"global destruction of objects". + +There is a way to tell perl to do complete cleanup: set the environment +variable PERL_DESTRUCT_LEVEL to a non-zero value. The t/TEST wrapper +does set this to 2, and this is what you need to do too, if you don't +want to see the "global leaks": For example, for "third-degreed" Perl: + + env PERL_DESTRUCT_LEVEL=2 ./perl.third -Ilib t/foo/bar.t + +(Note: the mod_perl apache module uses also this environment variable +for its own purposes and extended its semantics. Refer to the mod_perl +documentation for more information. Also, spawned threads do the +equivalent of setting this variable to the value 1.) + +If, at the end of a run you get the message I<N scalars leaked>, you +can recompile with C<-DDEBUG_LEAKING_SCALARS>, which will cause the +addresses of all those leaked SVs to be dumped along with details as to +where each SV was originally allocated. This information is also +displayed by Devel::Peek. Note that the extra details recorded with +each SV increases 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>, both memory and SV allocations go +through logging functions, which is handy for breakpoint setting. + +Unless C<-DPERL_MEM_LOG_NOIMPL> is also compiled, the logging functions +read $ENV{PERL_MEM_LOG} to determine whether to log the event, and if +so how: + + $ENV{PERL_MEM_LOG} =~ /m/ Log all memory ops + $ENV{PERL_MEM_LOG} =~ /s/ Log all SV ops + $ENV{PERL_MEM_LOG} =~ /t/ include timestamp in Log + $ENV{PERL_MEM_LOG} =~ /^(\d+)/ write to FD given (default is 2) + +Memory logging is somewhat similar to C<-Dm> but is independent of +C<-DDEBUGGING>, and at a higher level; all uses of Newx(), Renew(), and +Safefree() are logged with the caller's source code file and line +number (and C function name, if supported by the C compiler). In +contrast, C<-Dm> is directly at the point of C<malloc()>. SV logging is +similar. + +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. + +=head2 DDD over gdb + +Those debugging perl with the DDD frontend over gdb may find the +following useful: + +You can extend the data conversion shortcuts menu, so for example you +can display an SV's IV value with one click, without doing any typing. +To do that simply edit ~/.ddd/init file and add after: + + ! Display shortcuts. + Ddd*gdbDisplayShortcuts: \ + /t () // Convert to Bin\n\ + /d () // Convert to Dec\n\ + /x () // Convert to Hex\n\ + /o () // Convert to Oct(\n\ + +the following two lines: + + ((XPV*) (())->sv_any )->xpv_pv // 2pvx\n\ + ((XPVIV*) (())->sv_any )->xiv_iv // 2ivx + +so now you can do ivx and pvx lookups or you can plug there the sv_peek +"conversion": + + Perl_sv_peek(my_perl, (SV*)()) // sv_peek + +(The my_perl is for threaded builds.) Just remember that every line, +but the last one, should end with \n\ + +Alternatively edit the init file interactively via: 3rd mouse button -> +New Display -> Edit Menu + +Note: you can define up to 20 conversion shortcuts in the gdb section. + +=head2 Poison + +If you see in a debugger a memory area mysteriously full of 0xABABABAB +or 0xEFEFEFEF, you may be seeing the effect of the Poison() macros, see +L<perlclib>. + +=head2 Read-only optrees + +Under ithreads the optree is read only. If you want to enforce this, to +check for write accesses from buggy code, compile with +C<-DPL_OP_SLAB_ALLOC> to enable the OP slab allocator and +C<-DPERL_DEBUG_READONLY_OPS> to enable code that allocates op memory +via C<mmap>, and sets it read-only at run time. Any write access to an +op results in a C<SIGBUS> and abort. + +This code is intended for development only, and may not be portable +even to all Unix variants. Also, it is an 80% solution, in that it +isn't able to make all ops read only. Specifically it + +=over + +=item * 1 + +Only sets read-only on all slabs of ops at C<CHECK> time, hence ops +allocated later via C<require> or C<eval> will be re-write + +=item * 2 + +Turns an entire slab of ops read-write if the refcount of any op in the +slab needs to be decreased. + +=item * 3 + +Turns an entire slab of ops read-write if any op from the slab is +freed. + +=back + +It's not possible to turn the slabs to read-only after an action +requiring read-write access, as either can happen during op tree +building time, so there may still be legitimate write access. + +However, as an 80% solution it is still effective, as currently it +catches a write access during the generation of F<Config.pm>, which +means that we can't yet build F<perl> with this enabled. + +=head2 The .i Targets + +You can expand the macros in a F<foo.c> file by saying + + make foo.i + +which will expand the macros using cpp. Don't be scared by the results. + +=head1 AUTHOR + +This document was originally written by Nathan Torkington, and is +maintained by the perl5-porters mailing list. diff --git a/Master/tlpkg/tlperl/lib/pods/perlhacktut.pod b/Master/tlpkg/tlperl/lib/pods/perlhacktut.pod new file mode 100644 index 00000000000..33a9ef23e8d --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perlhacktut.pod @@ -0,0 +1,188 @@ +=encoding utf8 + +=for comment +Consistent formatting of this file is achieved with: + perl ./Porting/podtidy pod/perlhacktut.pod + +=head1 NAME + +perlhacktut - Walk through the creation of a simple C code patch + +=head1 DESCRIPTION + +This document takes you through a simple patch example. + +If you haven't read L<perlhack> yet, go do that first! You might also +want to read through L<perlsource> too. + +Once you're done here, check out L<perlhacktips> next. + +=head1 EXAMPLE OF A SIMPLE PATCH + +Let's take a simple patch from start to finish. + +Here's something Larry suggested: if a C<U> is the first active format +during a C<pack>, (for example, C<pack "U3C8", @stuff>) then the +resulting string should be treated as UTF-8 encoded. + +If you are working with a git clone of the Perl repository, you will +want to create a branch for your changes. This will make creating a +proper patch much simpler. See the L<perlgit> for details on how to do +this. + +=head2 Writing the patch + +How do we prepare to fix this up? First we locate the code in question +- the C<pack> happens at runtime, so it's going to be in one of the +F<pp> files. Sure enough, C<pp_pack> is in F<pp.c>. Since we're going +to be altering this file, let's copy it to F<pp.c~>. + +[Well, it was in F<pp.c> when this tutorial was written. It has now +been split off with C<pp_unpack> to its own file, F<pp_pack.c>] + +Now let's look over C<pp_pack>: we take a pattern into C<pat>, and then +loop over the pattern, taking each format character in turn into +C<datum_type>. Then for each possible format character, we swallow up +the other arguments in the pattern (a field width, an asterisk, and so +on) and convert the next chunk input into the specified format, adding +it onto the output SV C<cat>. + +How do we know if the C<U> is the first format in the C<pat>? Well, if +we have a pointer to the start of C<pat> then, if we see a C<U> we can +test whether we're still at the start of the string. So, here's where +C<pat> is set up: + + STRLEN fromlen; + register char *pat = SvPVx(*++MARK, fromlen); + register char *patend = pat + fromlen; + register I32 len; + I32 datumtype; + SV *fromstr; + +We'll have another string pointer in there: + + STRLEN fromlen; + register char *pat = SvPVx(*++MARK, fromlen); + register char *patend = pat + fromlen; + + char *patcopy; + register I32 len; + I32 datumtype; + SV *fromstr; + +And just before we start the loop, we'll set C<patcopy> to be the start +of C<pat>: + + items = SP - MARK; + MARK++; + sv_setpvn(cat, "", 0); + + patcopy = pat; + while (pat < patend) { + +Now if we see a C<U> which was at the start of the string, we turn on +the C<UTF8> flag for the output SV, C<cat>: + + + if (datumtype == 'U' && pat==patcopy+1) + + SvUTF8_on(cat); + if (datumtype == '#') { + while (pat < patend && *pat != '\n') + pat++; + +Remember that it has to be C<patcopy+1> because the first character of +the string is the C<U> which has been swallowed into C<datumtype!> + +Oops, we forgot one thing: what if there are spaces at the start of the +pattern? C<pack(" U*", @stuff)> will have C<U> as the first active +character, even though it's not the first thing in the pattern. In this +case, we have to advance C<patcopy> along with C<pat> when we see +spaces: + + if (isSPACE(datumtype)) + continue; + +needs to become + + if (isSPACE(datumtype)) { + patcopy++; + continue; + } + +OK. That's the C part done. Now we must do two additional things before +this patch is ready to go: we've changed the behaviour of Perl, and so +we must document that change. We must also provide some more regression +tests to make sure our patch works and doesn't create a bug somewhere +else along the line. + +=head2 Testing the patch + +The regression tests for each operator live in F<t/op/>, and so we make +a copy of F<t/op/pack.t> to F<t/op/pack.t~>. Now we can add our tests +to the end. First, we'll test that the C<U> does indeed create Unicode +strings. + +t/op/pack.t has a sensible ok() function, but if it didn't we could use +the one from t/test.pl. + + require './test.pl'; + plan( tests => 159 ); + +so instead of this: + + print 'not ' unless "1.20.300.4000" eq sprintf "%vd", + pack("U*",1,20,300,4000); + print "ok $test\n"; $test++; + +we can write the more sensible (see L<Test::More> for a full +explanation of is() and other testing functions). + + is( "1.20.300.4000", sprintf "%vd", pack("U*",1,20,300,4000), + "U* produces Unicode" ); + +Now we'll test that we got that space-at-the-beginning business right: + + is( "1.20.300.4000", sprintf "%vd", pack(" U*",1,20,300,4000), + " with spaces at the beginning" ); + +And finally we'll test that we don't make Unicode strings if C<U> is +B<not> the first active format: + + isnt( v1.20.300.4000, sprintf "%vd", pack("C0U*",1,20,300,4000), + "U* not first isn't Unicode" ); + +Mustn't forget to change the number of tests which appears at the top, +or else the automated tester will get confused. This will either look +like this: + + print "1..156\n"; + +or this: + + plan( tests => 156 ); + +We now compile up Perl, and run it through the test suite. Our new +tests pass, hooray! + +=head2 Documenting the patch + +Finally, the documentation. The job is never done until the paperwork +is over, so let's describe the change we've just made. The relevant +place is F<pod/perlfunc.pod>; again, we make a copy, and then we'll +insert this text in the description of C<pack>: + + =item * + + If the pattern begins with a C<U>, the resulting string will be treated + as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a string + with an initial C<U0>, and the bytes that follow will be interpreted as + Unicode characters. If you don't want this to happen, you can begin + your pattern with C<C0> (or anything else) to force Perl not to UTF-8 + encode your string, and then follow this with a C<U*> somewhere in your + pattern. + +=head2 Submit + +See L<perlhack> for details on how to submit this patch. + +=head1 AUTHOR + +This document was originally written by Nathan Torkington, and is +maintained by the perl5-porters mailing list. diff --git a/Master/tlpkg/tlperl/lib/pods/perlhaiku.pod b/Master/tlpkg/tlperl/lib/pods/perlhaiku.pod index c4b6ab79ef3..43215cde720 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlhaiku.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlhaiku.pod @@ -22,9 +22,9 @@ The build procedure is completely standard: Make perl executable and create a symlink for libperl: chmod a+x /boot/common/bin/perl - cd /boot/common/lib; ln -s perl5/5.12.3/BePC-haiku/CORE/libperl.so . + cd /boot/common/lib; ln -s perl5/5.14.2/BePC-haiku/CORE/libperl.so . -Replace C<5.12.3> with your respective version of Perl. +Replace C<5.14.2> with your respective version of Perl. =head1 KNOWN PROBLEMS @@ -57,7 +57,7 @@ fail. This is due to bugs in Haiku's network stack implementation. =head1 CONTACT For Haiku specific problems contact the HaikuPorts developers: -http://ports.haiku-files.org/ +L<http://ports.haiku-files.org/> The initial Haiku port was done by Ingo Weinhold <ingo_weinhold@gmx.de>. diff --git a/Master/tlpkg/tlperl/lib/pods/perlhist.pod b/Master/tlpkg/tlperl/lib/pods/perlhist.pod index 43ac8e91630..c694cc1c254 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlhist.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlhist.pod @@ -1,3 +1,5 @@ +=encoding utf8 + =head1 NAME perlhist - the Perl history records @@ -26,7 +28,9 @@ Larry Wall, Andy Dougherty, Tom Christiansen, Charles Bailey, Nick Ing-Simmons, Chip Salzenberg, Tim Bunce, Malcolm Beattie, Gurusamy Sarathy, Graham Barr, Jarkko Hietaniemi, Hugo van der Sanden, Michael Schwern, Rafael Garcia-Suarez, Nicholas Clark, Richard Clamp, -Leon Brocard, Dave Mitchell, Jesse Vincent, Ricardo Signes, Steve Hay. +Leon Brocard, Dave Mitchell, Jesse Vincent, Ricardo Signes, Steve Hay, +Matt S Trout, David Golden, Florian Ragwitz, Tatsuhiko Miyagawa, +Chris C<BinGOs> Williams, Zefram and Ævar Arnfjörð Bjarmason. =head2 PUMPKIN? @@ -68,7 +72,7 @@ the strings?). 1.001..10 1988-Jan-30 1.011..14 1988-Feb-02 Schwern 1.0.15 2002-Dec-18 Modernization - Richard 1.0.16 2003-Dec-18 + Richard 1.0_16 2003-Dec-18 Larry 2.000 1988-Jun-05 @@ -324,6 +328,7 @@ the strings?). Leon 5.005_04-RC1 2004-Feb-05 5.005_04-RC2 2004-Feb-18 5.005_04 2004-Feb-23 + 5.005_05-RC1 2009-Feb-16 Sarathy 5.005_50 1998-Jul-26 The 5.6 development track. 5.005_51 1998-Aug-10 @@ -405,7 +410,7 @@ the strings?). Rafael 5.10.0 2007-Dec-18 - David 5.10.1-RC1 2009-Aug-06 The 5.10 maintenance track + David M 5.10.1-RC1 2009-Aug-06 The 5.10 maintenance track 5.10.1-RC2 2009-Aug-18 5.10.1 2009-Aug-22 @@ -415,16 +420,47 @@ the strings?). Jesse 5.11.3 2009-Dec-20 Ricardo 5.11.4 2010-Jan-20 Steve 5.11.5 2010-Feb-20 - Jesse 5.12.0-RC1 2010-Mar-29 + Jesse 5.12.0-RC0 2010-Mar-21 + 5.12.0-RC1 2010-Mar-29 + 5.12.0-RC2 2010-Apr-01 + 5.12.0-RC3 2010-Apr-02 + 5.12.0-RC4 2010-Apr-06 + 5.12.0-RC5 2010-Apr-09 Jesse 5.12.0 2010-Apr-12 - Jesse 5.12.1 2010-May-16 - Jesse 5.12.2 2010-Sep-06 + + Jesse 5.12.1-RC2 2010-May-13 The 5.12 maintenance track + 5.12.1-RC1 2010-May-09 + 5.12.1 2010-May-16 + 5.12.2-RC2 2010-Aug-31 + 5.12.2 2010-Sep-06 Ricardo 5.12.3-RC1 2011-Jan-09 Ricardo 5.12.3-RC2 2011-Jan-14 Ricardo 5.12.3-RC3 2011-Jan-17 Ricardo 5.12.3 2011-Jan-21 + Leon 5.13.0 2010-Apr-20 The 5.13 development track + Ricardo 5.13.1 2010-May-20 + Matt 5.13.2 2010-Jun-22 + David G 5.13.3 2010-Jul-20 + Florian 5.13.4 2010-Aug-20 + Steve 5.13.5 2010-Sep-19 + Miyagawa 5.13.6 2010-Oct-20 + BinGOs 5.13.7 2010-Nov-20 + Zefram 5.13.8 2010-Dec-20 + Jesse 5.13.9 2011-Jan-20 + Ævar 5.13.10 2011-Feb-20 + Florian 5.13.11 2011-Mar-20 + Jesse 5.14.0RC1 2011-Apr-20 + Jesse 5.14.0RC2 2011-May-04 + Jesse 5.14.0RC3 2011-May-11 + + Jesse 5.14.0 2011-May-14 The 5.14 maintenance track + Jesse 5.14.1 2011-Jun-16 + Florian 5.14.2-RC1 2011-Sep-19 + 5.14.2 2011-Sep-26 + + =head2 SELECTED RELEASE SIZES For example the notation "core: 212 29" in the release 1.000 means that @@ -499,6 +535,8 @@ explained below. 5.10.1 4858 98 7440 519 6195 921 6147 1751 5151 163 5.12.0 4999 100 1146 121 15227 2176 6400 1843 5342 168 5.12.1 5000 100 1146 121 15283 2178 6407 1846 5354 169 + 5.12.2 5003 100 1146 121 15404 2178 6413 1846 5376 170 + 5.12.3 5004 100 1146 121 15529 2180 6417 1848 5391 171 The "core"..."doc" mean the following files from the Perl source code distribution. The glob notation ** means recursively, (.) means @@ -772,6 +810,35 @@ the Perl source distribution for somewhat more selected releases. win32 1482 68 1485 68 1497 70 1841 73 1841 73 x2p 349 19 349 19 345 19 345 19 345 19 + ====================================================================== + + 5.12.2 5.12.3 + + apollo 0 3 0 3 + beos 4 4 4 4 + Configure 536 1 536 1 + Cross 118 15 118 15 + djgpp 17 7 17 7 + emacs 402 4 402 4 + epoc 31 8 31 8 + h2pl 12 15 12 15 + hints 368 97 368 97 + mad 174 8 174 8 + mpeix 45 6 45 6 + NetWare 466 61 466 61 + os2 507 70 507 70 + plan9 316 17 316 17 + Porting 750 54 750 54 + qnx 1 4 1 4 + symbian 288 54 288 54 + utils 269 27 269 27 + uts 8 3 8 3 + vmesa 21 4 21 4 + vms 646 18 644 18 + vos 16 8 16 8 + win32 1841 73 1841 73 + x2p 345 19 345 19 + =head2 SELECTED PATCH SIZES The "diff lines kB" means that for example the patch 5.003_08, to be @@ -878,7 +945,7 @@ Jarkko Hietaniemi <F<jhi@iki.fi>>. Thanks to the collective memory of the Perlfolk. In addition to the Keepers of the Pumpkin also Alan Champion, Mark Dominus, -Andreas König, John Macdonald, Matthias Neeracher, Jeff Okamoto, +Andreas KE<0xf6>nig, John Macdonald, Matthias Neeracher, Jeff Okamoto, Michael Peppler, Randal Schwartz, and Paul D. Smith sent corrections and additions. Abigail added file and patch size data for the 5.6.0 - 5.10 era. diff --git a/Master/tlpkg/tlperl/lib/pods/perlhpux.pod b/Master/tlpkg/tlperl/lib/pods/perlhpux.pod index df3e6a8ef41..a1b59dec8d1 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlhpux.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlhpux.pod @@ -41,7 +41,7 @@ of Perl and the updated modules. The official (threaded) builds from HP, as they are shipped on the Application DVD/CD's are available on -http://www.software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=PERL +L<http://www.software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=PERL> for both PA-RISC and IPF (Itanium Processor Family). They are built with the HP ANSI-C compiler. Up till 5.8.8 that was done by ActiveState. @@ -69,7 +69,7 @@ HP has asked the porting centre to move Open Source binaries from /opt to /usr/local, so binaries produced since the start of July 2002 are located in /usr/local. -One of HP porting centres URL's is http://hpux.connect.org.uk/ +One of HP porting centres URL's is L<http://hpux.connect.org.uk/> The port currently available is built with GNU gcc. =head2 Compiling Perl 5 on HP-UX @@ -122,7 +122,7 @@ ends as shown in the following table: | cores | | PA-8900/rp34x0 | 2014 | +--------+----------------+----------------+-----------------+ -From http://www.hp.com/products1/evolution/9000/faqs.html +From L<http://www.hp.com/products1/evolution/9000/faqs.html> The last order date for HP 9000 systems was December 31, 2008. @@ -272,7 +272,7 @@ support all versions of HP-UX, here is a short list 11.31 11i v3 64 PA & IPF See for the full list of hardware/OS support and expected end-of-life -http://www.hp.com/go/hpuxservermatrix +L<http://www.hp.com/go/hpuxservermatrix> =head2 Building Dynamic Extensions on HP-UX @@ -402,16 +402,16 @@ for updates/patches. Enter "ANSI" as keyword. When you are going to use the GNU C compiler (gcc), and you don't have gcc yet, you can either build it yourself from the sources (available -from e.g. http://www.gnu.ai.mit.edu/software/gcc/releases.html) or fetch +from e.g. L<http://www.gnu.ai.mit.edu/software/gcc/releases.html>) or fetch a prebuilt binary from the HP porting center. gcc prebuilds can be fetched from -http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,547,00.html +L<http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,547,00.html> (Browse through the list, because there are often multiple versions of the same package available). Above mentioned distributions are depots. H.Merijn Brand has made prebuilt -gcc binaries available on http://mirrors.develooper.com/hpux/ and/or -http://www.cmve.net/~merijn/ for HP-UX 10.20, HP-UX 11.00, HP-UX 11.11 +gcc binaries available on L<http://mirrors.develooper.com/hpux/> and/or +L<http://www.cmve.net/~merijn/> for HP-UX 10.20, HP-UX 11.00, HP-UX 11.11 (HP-UX 11i v1), and HP-UX 11.23 (HP-UX 11i v2) in both 32- and 64-bit versions. These are bzipped tar archives that also include recent GNU binutils and GNU gdb. Read the instructions on that page to rebuild gcc @@ -481,7 +481,7 @@ HP-UX versions before 10.30 require a separate installation of a POSIX threads library package. Two examples are the HP DCE package, available on "HP-UX Hardware Extensions 3.0, Install and Core OS, Release 10.20, April 1999 (B3920-13941)" or the Freely available PTH package, available -on H.Merijn's site (http://mirrors.develooper.com/hpux/). The use of PTH +on H.Merijn's site (L<http://mirrors.develooper.com/hpux/>). The use of PTH will be unsupported in perl-5.12 and up and is rather buggy in 5.11.x. If you are going to use the HP DCE package, the library used for threading diff --git a/Master/tlpkg/tlperl/lib/pods/perlintern.pod b/Master/tlpkg/tlperl/lib/pods/perlintern.pod index b26ba099c34..5f09dcdc6d0 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlintern.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlintern.pod @@ -18,6 +18,56 @@ format but are not marked as part of the Perl API. In other words, B<they are not for use in extensions>! +=head1 Compile-time scope hooks + +=over 8 + +=item BhkENTRY +X<BhkENTRY> + +Return an entry from the BHK structure. I<which> is a preprocessor token +indicating which entry to return. If the appropriate flag is not set +this will return NULL. The type of the return value depends on which +entry you ask for. + +NOTE: this function is experimental and may change or be +removed without notice. + + void * BhkENTRY(BHK *hk, which) + +=for hackers +Found in file op.h + +=item BhkFLAGS +X<BhkFLAGS> + +Return the BHK's flags. + +NOTE: this function is experimental and may change or be +removed without notice. + + U32 BhkFLAGS(BHK *hk) + +=for hackers +Found in file op.h + +=item CALL_BLOCK_HOOKS +X<CALL_BLOCK_HOOKS> + +Call all the registered block hooks for type I<which>. I<which> is a +preprocessing token; the type of I<arg> depends on I<which>. + +NOTE: this function is experimental and may change or be +removed without notice. + + void CALL_BLOCK_HOOKS(which, arg) + +=for hackers +Found in file op.h + + +=back + =head1 CV reference counts and CvOUTSIDE =over 8 @@ -80,6 +130,236 @@ Found in file cv.h =back +=head1 Embedding Functions + +=over 8 + +=item cv_clone +X<cv_clone> + +Clone a CV: make a new CV which points to the same code etc, but which +has a newly-created pad built by copying the prototype pad and capturing +any outer lexicals. + + CV* cv_clone(CV* proto) + +=for hackers +Found in file pad.c + +=item cv_dump +X<cv_dump> + +dump the contents of a CV + + void cv_dump(const CV *cv, const char *title) + +=for hackers +Found in file pad.c + +=item do_dump_pad +X<do_dump_pad> + +Dump the contents of a padlist + + void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full) + +=for hackers +Found in file pad.c + +=item intro_my +X<intro_my> + +"Introduce" my variables to visible status. + + U32 intro_my() + +=for hackers +Found in file pad.c + +=item pad_add_anon +X<pad_add_anon> + +Add an anon code entry to the current compiling pad + + PADOFFSET pad_add_anon(SV* sv, OPCODE op_type) + +=for hackers +Found in file pad.c + +=item pad_add_name +X<pad_add_name> + +Create a new name and associated PADMY SV in the current pad; return the +offset. +If C<typestash> is valid, the name is for a typed lexical; set the +name's stash to that value. +If C<ourstash> is valid, it's an our lexical, set the name's +SvOURSTASH to that value + +If fake, it means we're cloning an existing entry + +NOTE: this function is experimental and may change or be +removed without notice. + + PADOFFSET pad_add_name(const char *name, const STRLEN len, const U32 flags, HV *typestash, HV *ourstash) + +=for hackers +Found in file pad.c + +=item pad_alloc +X<pad_alloc> + +Allocate a new my or tmp pad entry. For a my, simply push a null SV onto +the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards +for a slot which has no name and no active value. + + PADOFFSET pad_alloc(I32 optype, U32 tmptype) + +=for hackers +Found in file pad.c + +=item pad_block_start +X<pad_block_start> + +Update the pad compilation state variables on entry to a new block + + void pad_block_start(int full) + +=for hackers +Found in file pad.c + +=item pad_check_dup +X<pad_check_dup> + +Check for duplicate declarations: report any of: + * a my in the current scope with the same name; + * an our (anywhere in the pad) with the same name and the same stash + as C<ourstash> +C<is_our> indicates that the name to check is an 'our' declaration + + void pad_check_dup(SV *name, const U32 flags, const HV *ourstash) + +=for hackers +Found in file pad.c + +=item pad_findlex +X<pad_findlex> + +Find a named lexical anywhere in a chain of nested pads. Add fake entries +in the inner pads if it's found in an outer one. + +Returns the offset in the bottom pad of the lex or the fake lex. +cv is the CV in which to start the search, and seq is the current cop_seq +to match against. If warn is true, print appropriate warnings. The out_* +vars return values, and so are pointers to where the returned values +should be stored. out_capture, if non-null, requests that the innermost +instance of the lexical is captured; out_name_sv is set to the innermost +matched namesv or fake namesv; out_flags returns the flags normally +associated with the IVX field of a fake namesv. + +Note that pad_findlex() is recursive; it recurses up the chain of CVs, +then comes back down, adding fake entries as it goes. It has to be this way +because fake namesvs in anon protoypes have to store in xlow the index into +the parent pad. + + PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags) + +=for hackers +Found in file pad.c + +=item pad_fixup_inner_anons +X<pad_fixup_inner_anons> + +For any anon CVs in the pad, change CvOUTSIDE of that CV from +old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be +moved to a pre-existing CV struct. + + void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) + +=for hackers +Found in file pad.c + +=item pad_free +X<pad_free> + +Free the SV at offset po in the current pad. + + void pad_free(PADOFFSET po) + +=for hackers +Found in file pad.c + +=item pad_leavemy +X<pad_leavemy> + +Cleanup at end of scope during compilation: set the max seq number for +lexicals in this scope and warn of any lexicals that never got introduced. + + void pad_leavemy() + +=for hackers +Found in file pad.c + +=item pad_push +X<pad_push> + +Push a new pad frame onto the padlist, unless there's already a pad at +this depth, in which case don't bother creating a new one. Then give +the new pad an @_ in slot zero. + + void pad_push(PADLIST *padlist, int depth) + +=for hackers +Found in file pad.c + +=item pad_reset +X<pad_reset> + +Mark all the current temporaries for reuse + + void pad_reset() + +=for hackers +Found in file pad.c + +=item pad_setsv +X<pad_setsv> + +Set the entry at offset po in the current pad to sv. +Use the macro PAD_SETSV() rather than calling this function directly. + + void pad_setsv(PADOFFSET po, SV* sv) + +=for hackers +Found in file pad.c + +=item pad_swipe +X<pad_swipe> + +Abandon the tmp in the current pad at offset po and replace with a +new one. + + void pad_swipe(PADOFFSET po, bool refadjust) + +=for hackers +Found in file pad.c + +=item pad_tidy +X<pad_tidy> + +Tidy up a pad after we've finished compiling it: + * remove most stuff from the pads of anonsub prototypes; + * give it a @_; + * mark tmps as such. + + void pad_tidy(padtidy_type type) + +=for hackers +Found in file pad.c + + +=back + =head1 Functions in file pad.h @@ -411,16 +691,91 @@ Found in file gv.c =over 8 +=item hv_ename_add +X<hv_ename_add> + +Adds a name to a stash's internal list of effective names. See +C<hv_ename_delete>. + +This is called when a stash is assigned to a new location in the symbol +table. + + void hv_ename_add(HV *hv, const char *name, U32 len, U32 flags) + +=for hackers +Found in file hv.c + +=item hv_ename_delete +X<hv_ename_delete> + +Removes a name from a stash's internal list of effective names. If this is +the name returned by C<HvENAME>, then another name in the list will take +its place (C<HvENAME> will use it). + +This is called when a stash is deleted from the symbol table. + + void hv_ename_delete(HV *hv, const char *name, U32 len, U32 flags) + +=for hackers +Found in file hv.c + =item refcounted_he_chain_2hv X<refcounted_he_chain_2hv> -Generates and returns a C<HV *> by walking up the tree starting at the passed -in C<struct refcounted_he *>. +Generates and returns a C<HV *> representing the content of a +C<refcounted_he> chain. +I<flags> is currently unused and must be zero. -NOTE: this function is experimental and may change or be -removed without notice. + HV * refcounted_he_chain_2hv(const struct refcounted_he *c, U32 flags) + +=for hackers +Found in file hv.c + +=item refcounted_he_fetch_pv +X<refcounted_he_fetch_pv> + +Like L</refcounted_he_fetch_pvn>, but takes a nul-terminated string +instead of a string/length pair. + + SV * refcounted_he_fetch_pv(const struct refcounted_he *chain, const char *key, U32 hash, U32 flags) + +=for hackers +Found in file hv.c - HV * refcounted_he_chain_2hv(const struct refcounted_he *c) +=item refcounted_he_fetch_pvn +X<refcounted_he_fetch_pvn> + +Search along a C<refcounted_he> chain for an entry with the key specified +by I<keypv> and I<keylen>. If I<flags> has the C<REFCOUNTED_HE_KEY_UTF8> +bit set, the key octets are interpreted as UTF-8, otherwise they +are interpreted as Latin-1. I<hash> is a precomputed hash of the key +string, or zero if it has not been precomputed. Returns a mortal scalar +representing the value associated with the key, or C<&PL_sv_placeholder> +if there is no value associated with the key. + + SV * refcounted_he_fetch_pvn(const struct refcounted_he *chain, const char *keypv, STRLEN keylen, U32 hash, U32 flags) + +=for hackers +Found in file hv.c + +=item refcounted_he_fetch_pvs +X<refcounted_he_fetch_pvs> + +Like L</refcounted_he_fetch_pvn>, but takes a literal string instead of +a string/length pair, and no precomputed hash. + + SV * refcounted_he_fetch_pvs(const struct refcounted_he *chain, const char *key, U32 flags) + +=for hackers +Found in file hv.h + +=item refcounted_he_fetch_sv +X<refcounted_he_fetch_sv> + +Like L</refcounted_he_fetch_pvn>, but takes a Perl scalar instead of a +string/length pair. + + SV * refcounted_he_fetch_sv(const struct refcounted_he *chain, SV *key, U32 hash, U32 flags) =for hackers Found in file hv.c @@ -428,29 +783,93 @@ Found in file hv.c =item refcounted_he_free X<refcounted_he_free> -Decrements the reference count of the passed in C<struct refcounted_he *> -by one. If the reference count reaches zero the structure's memory is freed, -and C<refcounted_he_free> iterates onto the parent node. - -NOTE: this function is experimental and may change or be -removed without notice. +Decrements the reference count of a C<refcounted_he> by one. If the +reference count reaches zero the structure's memory is freed, which +(recursively) causes a reduction of its parent C<refcounted_he>'s +reference count. It is safe to pass a null pointer to this function: +no action occurs in this case. void refcounted_he_free(struct refcounted_he *he) =for hackers Found in file hv.c -=item refcounted_he_new -X<refcounted_he_new> +=item refcounted_he_inc +X<refcounted_he_inc> -Creates a new C<struct refcounted_he>. As S<key> is copied, and value is -stored in a compact form, all references remain the property of the caller. -The C<struct refcounted_he> is returned with a reference count of 1. +Increment the reference count of a C<refcounted_he>. The pointer to the +C<refcounted_he> is also returned. It is safe to pass a null pointer +to this function: no action occurs and a null pointer is returned. -NOTE: this function is experimental and may change or be -removed without notice. + struct refcounted_he * refcounted_he_inc(struct refcounted_he *he) + +=for hackers +Found in file hv.c + +=item refcounted_he_new_pv +X<refcounted_he_new_pv> - struct refcounted_he * refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value) +Like L</refcounted_he_new_pvn>, but takes a nul-terminated string instead +of a string/length pair. + + struct refcounted_he * refcounted_he_new_pv(struct refcounted_he *parent, const char *key, U32 hash, SV *value, U32 flags) + +=for hackers +Found in file hv.c + +=item refcounted_he_new_pvn +X<refcounted_he_new_pvn> + +Creates a new C<refcounted_he>. This consists of a single key/value +pair and a reference to an existing C<refcounted_he> chain (which may +be empty), and thus forms a longer chain. When using the longer chain, +the new key/value pair takes precedence over any entry for the same key +further along the chain. + +The new key is specified by I<keypv> and I<keylen>. If I<flags> has +the C<REFCOUNTED_HE_KEY_UTF8> bit set, the key octets are interpreted +as UTF-8, otherwise they are interpreted as Latin-1. I<hash> is +a precomputed hash of the key string, or zero if it has not been +precomputed. + +I<value> is the scalar value to store for this key. I<value> is copied +by this function, which thus does not take ownership of any reference +to it, and later changes to the scalar will not be reflected in the +value visible in the C<refcounted_he>. Complex types of scalar will not +be stored with referential integrity, but will be coerced to strings. +I<value> may be either null or C<&PL_sv_placeholder> to indicate that no +value is to be associated with the key; this, as with any non-null value, +takes precedence over the existence of a value for the key further along +the chain. + +I<parent> points to the rest of the C<refcounted_he> chain to be +attached to the new C<refcounted_he>. This function takes ownership +of one reference to I<parent>, and returns one reference to the new +C<refcounted_he>. + + struct refcounted_he * refcounted_he_new_pvn(struct refcounted_he *parent, const char *keypv, STRLEN keylen, U32 hash, SV *value, U32 flags) + +=for hackers +Found in file hv.c + +=item refcounted_he_new_pvs +X<refcounted_he_new_pvs> + +Like L</refcounted_he_new_pvn>, but takes a literal string instead of +a string/length pair, and no precomputed hash. + + struct refcounted_he * refcounted_he_new_pvs(struct refcounted_he *parent, const char *key, SV *value, U32 flags) + +=for hackers +Found in file hv.h + +=item refcounted_he_new_sv +X<refcounted_he_new_sv> + +Like L</refcounted_he_new_pvn>, but takes a Perl scalar instead of a +string/length pair. + + struct refcounted_he * refcounted_he_new_sv(struct refcounted_he *parent, SV *key, U32 hash, SV *value, U32 flags) =for hackers Found in file hv.c @@ -506,6 +925,27 @@ Triggered by clearing %^H, resets C<PL_compiling.cop_hints_hash>. =for hackers Found in file mg.c +=item magic_methcall +X<magic_methcall> + +Invoke a magic method (like FETCH). + +* sv and mg are the tied thingy and the tie magic; +* meth is the name of the method to call; +* argc is the number of args (in addition to $self) to pass to the method; + the args themselves are any values following the argc argument. +* flags: + G_DISCARD: invoke method with G_DISCARD flag and don't return a value + G_UNDEF_FILL: fill the stack with argc pointers to PL_sv_undef. + +Returns the SV (if any) returned by the method, or NULL on failure. + + + SV* magic_methcall(SV *sv, const MAGIC *mg, const char *meth, U32 flags, U32 argc, ...) + +=for hackers +Found in file mg.c + =item magic_sethint X<magic_sethint> @@ -573,6 +1013,32 @@ by the C<setisa> magic, should not need to invoke directly. =for hackers Found in file mro.c +=item mro_package_moved +X<mro_package_moved> + +Call this function to signal to a stash that it has been assigned to +another spot in the stash hierarchy. C<stash> is the stash that has been +assigned. C<oldstash> is the stash it replaces, if any. C<gv> is the glob +that is actually being assigned to. + +This can also be called with a null first argument to +indicate that C<oldstash> has been deleted. + +This function invalidates isa caches on the old stash, on all subpackages +nested inside it, and on the subclasses of all those, including +non-existent packages that have corresponding entries in C<stash>. + +It also sets the effective names (C<HvENAME>) on all the stashes as +appropriate. + +If the C<gv> is present and is not in the symbol table, then this function +simply returns. This checked will be skipped if C<flags & 1>. + + void mro_package_moved(HV * const stash, HV * const oldstash, const GV * const gv, U32 flags) + +=for hackers +Found in file mro.c + =back @@ -628,7 +1094,17 @@ in PL_op->op_targ), wasting a name SV for them doesn't make sense. The SVs in the names AV have their PV being the name of the variable. xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for -which the name is valid. For typed lexicals name SV is SVt_PVMG and SvSTASH +which the name is valid (accessed through the macros COP_SEQ_RANGE_LOW and +_HIGH). During compilation, these fields may hold the special value +PERL_PADSEQ_INTRO to indicate various stages: + + COP_SEQ_RANGE_LOW _HIGH + ----------------- ----- + PERL_PADSEQ_INTRO 0 variable not yet introduced: { my ($x + valid-seq# PERL_PADSEQ_INTRO variable in scope: { my ($x) + valid-seq# valid-seq# compilation of scope complete: { my ($x) } + +For typed lexicals name SV is SVt_PVMG and SvSTASH points at the type. For C<our> lexicals, the type is also SVt_PVMG, with the SvOURSTASH slot pointing at the stash of the associated global (so that duplicate C<our> declarations in the same package can be detected). SvUVX is @@ -664,172 +1140,6 @@ For state vars, SVs_PADSTALE is overloaded to mean 'not yet initialised' =for hackers Found in file pad.c -=item cv_clone -X<cv_clone> - -Clone a CV: make a new CV which points to the same code etc, but which -has a newly-created pad built by copying the prototype pad and capturing -any outer lexicals. - - CV* cv_clone(CV* proto) - -=for hackers -Found in file pad.c - -=item cv_dump -X<cv_dump> - -dump the contents of a CV - - void cv_dump(const CV *cv, const char *title) - -=for hackers -Found in file pad.c - -=item do_dump_pad -X<do_dump_pad> - -Dump the contents of a padlist - - void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full) - -=for hackers -Found in file pad.c - -=item intro_my -X<intro_my> - -"Introduce" my variables to visible status. - - U32 intro_my() - -=for hackers -Found in file pad.c - -=item pad_add_anon -X<pad_add_anon> - -Add an anon code entry to the current compiling pad - - PADOFFSET pad_add_anon(SV* sv, OPCODE op_type) - -=for hackers -Found in file pad.c - -=item pad_add_name -X<pad_add_name> - -Create a new name and associated PADMY SV in the current pad; return the -offset. -If C<typestash> is valid, the name is for a typed lexical; set the -name's stash to that value. -If C<ourstash> is valid, it's an our lexical, set the name's -SvOURSTASH to that value - -If fake, it means we're cloning an existing entry - -NOTE: this function is experimental and may change or be -removed without notice. - - PADOFFSET pad_add_name(const char *name, const STRLEN len, const U32 flags, HV *typestash, HV *ourstash) - -=for hackers -Found in file pad.c - -=item pad_alloc -X<pad_alloc> - -Allocate a new my or tmp pad entry. For a my, simply push a null SV onto -the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards -for a slot which has no name and no active value. - - PADOFFSET pad_alloc(I32 optype, U32 tmptype) - -=for hackers -Found in file pad.c - -=item pad_block_start -X<pad_block_start> - -Update the pad compilation state variables on entry to a new block - - void pad_block_start(int full) - -=for hackers -Found in file pad.c - -=item pad_check_dup -X<pad_check_dup> - -Check for duplicate declarations: report any of: - * a my in the current scope with the same name; - * an our (anywhere in the pad) with the same name and the same stash - as C<ourstash> -C<is_our> indicates that the name to check is an 'our' declaration - - void pad_check_dup(SV *name, const U32 flags, const HV *ourstash) - -=for hackers -Found in file pad.c - -=item pad_findlex -X<pad_findlex> - -Find a named lexical anywhere in a chain of nested pads. Add fake entries -in the inner pads if it's found in an outer one. - -Returns the offset in the bottom pad of the lex or the fake lex. -cv is the CV in which to start the search, and seq is the current cop_seq -to match against. If warn is true, print appropriate warnings. The out_* -vars return values, and so are pointers to where the returned values -should be stored. out_capture, if non-null, requests that the innermost -instance of the lexical is captured; out_name_sv is set to the innermost -matched namesv or fake namesv; out_flags returns the flags normally -associated with the IVX field of a fake namesv. - -Note that pad_findlex() is recursive; it recurses up the chain of CVs, -then comes back down, adding fake entries as it goes. It has to be this way -because fake namesvs in anon protoypes have to store in xlow the index into -the parent pad. - - PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags) - -=for hackers -Found in file pad.c - -=item pad_fixup_inner_anons -X<pad_fixup_inner_anons> - -For any anon CVs in the pad, change CvOUTSIDE of that CV from -old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be -moved to a pre-existing CV struct. - - void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) - -=for hackers -Found in file pad.c - -=item pad_free -X<pad_free> - -Free the SV at offset po in the current pad. - - void pad_free(PADOFFSET po) - -=for hackers -Found in file pad.c - -=item pad_leavemy -X<pad_leavemy> - -Cleanup at end of scope during compilation: set the max seq number for -lexicals in this scope and warn of any lexicals that never got introduced. - - void pad_leavemy() - -=for hackers -Found in file pad.c - =item pad_new X<pad_new> @@ -846,80 +1156,6 @@ can be OR'ed together: =for hackers Found in file pad.c -=item pad_push -X<pad_push> - -Push a new pad frame onto the padlist, unless there's already a pad at -this depth, in which case don't bother creating a new one. Then give -the new pad an @_ in slot zero. - - void pad_push(PADLIST *padlist, int depth) - -=for hackers -Found in file pad.c - -=item pad_reset -X<pad_reset> - -Mark all the current temporaries for reuse - - void pad_reset() - -=for hackers -Found in file pad.c - -=item pad_setsv -X<pad_setsv> - -Set the entry at offset po in the current pad to sv. -Use the macro PAD_SETSV() rather than calling this function directly. - - void pad_setsv(PADOFFSET po, SV* sv) - -=for hackers -Found in file pad.c - -=item pad_swipe -X<pad_swipe> - -Abandon the tmp in the current pad at offset po and replace with a -new one. - - void pad_swipe(PADOFFSET po, bool refadjust) - -=for hackers -Found in file pad.c - -=item pad_tidy -X<pad_tidy> - -Tidy up a pad after we've finished compiling it: - * remove most stuff from the pads of anonsub prototypes; - * give it a @_; - * mark tmps as such. - - void pad_tidy(padtidy_type type) - -=for hackers -Found in file pad.c - -=item pad_undef -X<pad_undef> - -Free the padlist associated with a CV. -If parts of it happen to be current, we null the relevant -PL_*pad* global vars so that we don't have any dangling references left. -We also repoint the CvOUTSIDE of any about-to-be-orphaned -inner subs to the outer of this cv. - -(This function should really be called pad_free, but the name was already -taken) - - void pad_undef(CV* cv) - -=for hackers -Found in file pad.c - =back @@ -1154,7 +1390,13 @@ Found in file sv.c =head1 Undocumented functions -These functions are currently undocumented: +The following functions have been flagged as part of the public API, +but are currently undocumented. Use them at your own risk, as the +interfaces are subject to change. + +If you use one of them, you may wish to consider creating and submitting +documentation for it. If your patch is accepted, this will indicate that +the interface is stable (unless it is explicitly marked otherwise). =over @@ -1164,9 +1406,30 @@ X<F0convert> =item Slab_to_rw X<Slab_to_rw> +=item _append_range_to_invlist +X<_append_range_to_invlist> + +=item _new_invlist +X<_new_invlist> + +=item _swash_inversion_hash +X<_swash_inversion_hash> + +=item _swash_to_invlist +X<_swash_to_invlist> + +=item add_alternate +X<add_alternate> + +=item add_cp_to_invlist +X<add_cp_to_invlist> + =item add_data X<add_data> +=item add_range_to_invlist +X<add_range_to_invlist> + =item add_utf16_textfilter X<add_utf16_textfilter> @@ -1188,18 +1451,12 @@ X<amagic_i_ncmp> =item amagic_ncmp X<amagic_ncmp> -=item anonymise_cv -X<anonymise_cv> +=item anonymise_cv_maybe +X<anonymise_cv_maybe> =item ao X<ao> -=item append_elem -X<append_elem> - -=item append_list -X<append_list> - =item append_madprops X<append_madprops> @@ -1212,6 +1469,9 @@ X<apply_attrs> =item apply_attrs_my X<apply_attrs_my> +=item assert_uft8_cache_coherent +X<assert_uft8_cache_coherent> + =item av_reify X<av_reify> @@ -1248,135 +1508,15 @@ X<check_type_and_open> =item check_uni X<check_uni> +=item check_utf8_print +X<check_utf8_print> + =item checkcomma X<checkcomma> =item checkposixcc X<checkposixcc> -=item ck_anoncode -X<ck_anoncode> - -=item ck_bitop -X<ck_bitop> - -=item ck_concat -X<ck_concat> - -=item ck_defined -X<ck_defined> - -=item ck_delete -X<ck_delete> - -=item ck_die -X<ck_die> - -=item ck_each -X<ck_each> - -=item ck_eof -X<ck_eof> - -=item ck_eval -X<ck_eval> - -=item ck_exec -X<ck_exec> - -=item ck_exists -X<ck_exists> - -=item ck_exit -X<ck_exit> - -=item ck_ftst -X<ck_ftst> - -=item ck_fun -X<ck_fun> - -=item ck_glob -X<ck_glob> - -=item ck_grep -X<ck_grep> - -=item ck_index -X<ck_index> - -=item ck_join -X<ck_join> - -=item ck_lfun -X<ck_lfun> - -=item ck_listiob -X<ck_listiob> - -=item ck_match -X<ck_match> - -=item ck_method -X<ck_method> - -=item ck_null -X<ck_null> - -=item ck_open -X<ck_open> - -=item ck_readline -X<ck_readline> - -=item ck_repeat -X<ck_repeat> - -=item ck_require -X<ck_require> - -=item ck_return -X<ck_return> - -=item ck_rfun -X<ck_rfun> - -=item ck_rvconst -X<ck_rvconst> - -=item ck_sassign -X<ck_sassign> - -=item ck_select -X<ck_select> - -=item ck_shift -X<ck_shift> - -=item ck_sort -X<ck_sort> - -=item ck_spair -X<ck_spair> - -=item ck_split -X<ck_split> - -=item ck_subr -X<ck_subr> - -=item ck_substr -X<ck_substr> - -=item ck_svconst -X<ck_svconst> - -=item ck_trunc -X<ck_trunc> - -=item ck_unpack -X<ck_unpack> - =item ckwarn_common X<ckwarn_common> @@ -1389,9 +1529,6 @@ X<cl_anything> =item cl_init X<cl_init> -=item cl_init_zero -X<cl_init_zero> - =item cl_is_anything X<cl_is_anything> @@ -1419,9 +1556,18 @@ X<create_eval_scope> =item curmad X<curmad> +=item curse +X<curse> + =item cv_ckproto_len X<cv_ckproto_len> +=item cvgv_set +X<cvgv_set> + +=item cvstash_set +X<cvstash_set> + =item deb_curcv X<deb_curcv> @@ -1449,8 +1595,8 @@ X<deprecate_commaless_var_list> =item destroy_matcher X<destroy_matcher> -=item die_where -X<die_where> +=item die_unwind +X<die_unwind> =item div128 X<div128> @@ -1464,9 +1610,6 @@ X<do_aexec5> =item do_chomp X<do_chomp> -=item do_chop -X<do_chop> - =item do_delete_local X<do_delete_local> @@ -1488,9 +1631,6 @@ X<do_ipcctl> =item do_ipcget X<do_ipcget> -=item do_kv -X<do_kv> - =item do_msgrcv X<do_msgrcv> @@ -1701,9 +1841,6 @@ X<free_tied_hv_pool> =item gen_constant_list X<gen_constant_list> -=item get_arena -X<get_arena> - =item get_aux_mg X<get_aux_mg> @@ -1716,9 +1853,6 @@ X<get_debug_opts> =item get_hash_seed X<get_hash_seed> -=item get_isa_hash -X<get_isa_hash> - =item get_no_modify X<get_no_modify> @@ -1743,6 +1877,12 @@ X<glob_assign_glob> =item glob_assign_ref X<glob_assign_ref> +=item grok_bslash_c +X<grok_bslash_c> + +=item grok_bslash_o +X<grok_bslash_o> + =item group_end X<group_end> @@ -1755,6 +1895,12 @@ X<gv_get_super_pkg> =item gv_init_sv X<gv_init_sv> +=item gv_magicalize_isa +X<gv_magicalize_isa> + +=item gv_magicalize_overload +X<gv_magicalize_overload> + =item hfreeentries X<hfreeentries> @@ -1767,9 +1913,6 @@ X<hv_auxinit> =item hv_backreferences_p X<hv_backreferences_p> -=item hv_copy_hints_hv -X<hv_copy_hints_hv> - =item hv_delete_common X<hv_delete_common> @@ -1782,6 +1925,9 @@ X<hv_magic_check> =item hv_notallowed X<hv_notallowed> +=item hv_undef_flags +X<hv_undef_flags> + =item incline X<incline> @@ -1833,6 +1979,39 @@ X<intuit_more> =item invert X<invert> +=item invlist_array +X<invlist_array> + +=item invlist_destroy +X<invlist_destroy> + +=item invlist_extend +X<invlist_extend> + +=item invlist_intersection +X<invlist_intersection> + +=item invlist_len +X<invlist_len> + +=item invlist_max +X<invlist_max> + +=item invlist_set_len +X<invlist_set_len> + +=item invlist_set_max +X<invlist_set_max> + +=item invlist_trim +X<invlist_trim> + +=item invlist_union +X<invlist_union> + +=item invoke_exception_hook +X<invoke_exception_hook> + =item io_close X<io_close> @@ -1899,15 +2078,6 @@ X<keyword> =item keyword_plugin_standard X<keyword_plugin_standard> -=item lex_end -X<lex_end> - -=item lex_start -X<lex_start> - -=item linklist -X<linklist> - =item list X<list> @@ -1995,8 +2165,8 @@ X<magic_killbackrefs> =item magic_len X<magic_len> -=item magic_methcall -X<magic_methcall> +=item magic_methcall1 +X<magic_methcall1> =item magic_methpack X<magic_methpack> @@ -2133,6 +2303,12 @@ X<more_bodies> =item more_sv X<more_sv> +=item mro_clean_isarev +X<mro_clean_isarev> + +=item mro_gather_and_rename +X<mro_gather_and_rename> + =item mro_meta_dup X<mro_meta_dup> @@ -2145,6 +2321,9 @@ X<mul128> =item mulexp10 X<mulexp10> +=item munge_qwlist_to_paren_list +X<munge_qwlist_to_paren_list> + =item my_attrs X<my_attrs> @@ -2229,6 +2408,12 @@ X<my_letohl> =item my_letohs X<my_letohs> +=item my_lstat_flags +X<my_lstat_flags> + +=item my_stat_flags +X<my_stat_flags> + =item my_swabn X<my_swabn> @@ -2295,9 +2480,6 @@ X<nuke_stacks> =item num_overflow X<num_overflow> -=item offer_nice_chunk -X<offer_nice_chunk> - =item oopsAV X<oopsAV> @@ -2349,6 +2531,9 @@ X<pad_compname_type> =item pad_peg X<pad_peg> +=item padlist_dup +X<padlist_dup> + =item parse_body X<parse_body> @@ -2373,9 +2558,6 @@ X<pidgone> =item pm_description X<pm_description> -=item pmflag -X<pmflag> - =item pmop_xmldump X<pmop_xmldump> @@ -2385,8 +2567,8 @@ X<pmruntime> =item pmtrans X<pmtrans> -=item prepend_elem -X<prepend_elem> +=item populate_isa +X<populate_isa> =item prepend_madprops X<prepend_madprops> @@ -2418,12 +2600,6 @@ X<readpipe_override> =item ref_array_or_hash X<ref_array_or_hash> -=item refcounted_he_fetch -X<refcounted_he_fetch> - -=item refcounted_he_new_common -X<refcounted_he_new_common> - =item refcounted_he_value X<refcounted_he_value> @@ -2547,12 +2723,18 @@ X<regwhite> =item report_evil_fh X<report_evil_fh> +=item report_wrongway_fh +X<report_wrongway_fh> + =item require_tie_mod X<require_tie_mod> =item restore_magic X<restore_magic> +=item rpeep +X<rpeep> + =item rsignal_restore X<rsignal_restore> @@ -2577,33 +2759,18 @@ X<rxres_save> =item same_dirent X<same_dirent> -=item save_freeop -X<save_freeop> - =item save_hek_flags X<save_hek_flags> -=item save_hints -X<save_hints> - =item save_lines X<save_lines> =item save_magic X<save_magic> -=item save_op -X<save_op> - -=item save_pushi32ptr -X<save_pushi32ptr> - =item save_pushptri32ptr X<save_pushptri32ptr> -=item save_pushptrptr -X<save_pushptrptr> - =item save_scalar_at X<save_scalar_at> @@ -2661,9 +2828,6 @@ X<scan_trans> =item scan_word X<scan_word> -=item scope -X<scope> - =item search_const X<search_const> @@ -2676,6 +2840,12 @@ X<sequence_num> =item sequence_tail X<sequence_tail> +=item set_regclass_bit +X<set_regclass_bit> + +=item set_regclass_bit_fold +X<set_regclass_bit_fold> + =item share_hek_flags X<share_hek_flags> @@ -2748,15 +2918,24 @@ X<sv_2iuv_non_preserve> =item sv_add_backref X<sv_add_backref> +=item sv_catxmlpv +X<sv_catxmlpv> + =item sv_catxmlpvn X<sv_catxmlpvn> =item sv_catxmlsv X<sv_catxmlsv> +=item sv_compile_2op_is_broken +X<sv_compile_2op_is_broken> + =item sv_del_backref X<sv_del_backref> +=item sv_dup_common +X<sv_dup_common> + =item sv_dup_inc_multiple X<sv_dup_inc_multiple> @@ -2805,6 +2984,9 @@ X<swallow_bom> =item swash_get X<swash_get> +=item tied_method +X<tied_method> + =item to_byte_substr X<to_byte_substr> @@ -2832,12 +3014,21 @@ X<too_few_arguments> =item too_many_arguments X<too_many_arguments> +=item try_amagic_bin +X<try_amagic_bin> + +=item try_amagic_un +X<try_amagic_un> + =item uiv_2buf X<uiv_2buf> =item unpack_rec X<unpack_rec> +=item unreferenced_to_tmp_stack +X<unreferenced_to_tmp_stack> + =item unshare_hek X<unshare_hek> @@ -2856,6 +3047,9 @@ X<usage> =item utf16_textfilter X<utf16_textfilter> +=item utf8_mg_len_cache_update +X<utf8_mg_len_cache_update> + =item utf8_mg_pos_cache_update X<utf8_mg_pos_cache_update> @@ -2868,15 +3062,6 @@ X<validate_suid> =item varname X<varname> -=item vdie -X<vdie> - -=item vdie_common -X<vdie_common> - -=item vdie_croak_common -X<vdie_croak_common> - =item visit X<visit> @@ -2892,6 +3077,9 @@ X<wait4pid> =item watch X<watch> +=item with_queued_errors +X<with_queued_errors> + =item write_no_mem X<write_no_mem> @@ -2931,6 +3119,12 @@ X<xmldump_sub_perl> =item xmldump_vindent X<xmldump_vindent> +=item xs_apiversion_bootcheck +X<xs_apiversion_bootcheck> + +=item xs_version_bootcheck +X<xs_version_bootcheck> + =item yyerror X<yyerror> @@ -2940,6 +3134,9 @@ X<yylex> =item yyparse X<yyparse> +=item yyunlex +X<yyunlex> + =item yywarn X<yywarn> diff --git a/Master/tlpkg/tlperl/lib/pods/perlinterp.pod b/Master/tlpkg/tlperl/lib/pods/perlinterp.pod new file mode 100644 index 00000000000..74a5e4eb968 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perlinterp.pod @@ -0,0 +1,742 @@ +=encoding utf8 + +=for comment +Consistent formatting of this file is achieved with: + perl ./Porting/podtidy pod/perlinterp.pod + +=head1 NAME + +perlinterp - An overview of the Perl interpreter + +=head1 DESCRIPTION + +This document provides an overview of how the Perl interpreter works at +the level of C code, along with pointers to the relevant C source code +files. + +=head1 ELEMENTS OF THE INTERPRETER + +The work of the interpreter has two main stages: compiling the code +into the internal representation, or bytecode, and then executing it. +L<perlguts/Compiled code> explains exactly how the compilation stage +happens. + +Here is a short breakdown of perl's operation: + +=head2 Startup + +The action begins in F<perlmain.c>. (or F<miniperlmain.c> for miniperl) +This is very high-level code, enough to fit on a single screen, and it +resembles the code found in L<perlembed>; most of the real action takes +place in F<perl.c> + +F<perlmain.c> is generated by C<ExtUtils::Miniperl> from +F<miniperlmain.c> at make time, so you should make perl to follow this +along. + +First, F<perlmain.c> allocates some memory and constructs a Perl +interpreter, along these lines: + + 1 PERL_SYS_INIT3(&argc,&argv,&env); + 2 + 3 if (!PL_do_undump) { + 4 my_perl = perl_alloc(); + 5 if (!my_perl) + 6 exit(1); + 7 perl_construct(my_perl); + 8 PL_perl_destruct_level = 0; + 9 } + +Line 1 is a macro, and its definition is dependent on your operating +system. Line 3 references C<PL_do_undump>, a global variable - all +global variables in Perl start with C<PL_>. This tells you whether the +current running program was created with the C<-u> flag to perl and +then F<undump>, which means it's going to be false in any sane context. + +Line 4 calls a function in F<perl.c> to allocate memory for a Perl +interpreter. It's quite a simple function, and the guts of it looks +like this: + + my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter)); + +Here you see an example of Perl's system abstraction, which we'll see +later: C<PerlMem_malloc> is either your system's C<malloc>, or Perl's +own C<malloc> as defined in F<malloc.c> if you selected that option at +configure time. + +Next, in line 7, we construct the interpreter using perl_construct, +also in F<perl.c>; this sets up all the special variables that Perl +needs, the stacks, and so on. + +Now we pass Perl the command line options, and tell it to go: + + exitstatus = perl_parse(my_perl, xs_init, argc, argv, (char **)NULL); + if (!exitstatus) + perl_run(my_perl); + + exitstatus = perl_destruct(my_perl); + + perl_free(my_perl); + +C<perl_parse> is actually a wrapper around C<S_parse_body>, as defined +in F<perl.c>, which processes the command line options, sets up any +statically linked XS modules, opens the program and calls C<yyparse> to +parse it. + +=head2 Parsing + +The aim of this stage is to take the Perl source, and turn it into an +op tree. We'll see what one of those looks like later. Strictly +speaking, there's three things going on here. + +C<yyparse>, the parser, lives in F<perly.c>, although you're better off +reading the original YACC input in F<perly.y>. (Yes, Virginia, there +B<is> a YACC grammar for Perl!) The job of the parser is to take your +code and "understand" it, splitting it into sentences, deciding which +operands go with which operators and so on. + +The parser is nobly assisted by the lexer, which chunks up your input +into tokens, and decides what type of thing each token is: a variable +name, an operator, a bareword, a subroutine, a core function, and so +on. The main point of entry to the lexer is C<yylex>, and that and its +associated routines can be found in F<toke.c>. Perl isn't much like +other computer languages; it's highly context sensitive at times, it +can be tricky to work out what sort of token something is, or where a +token ends. As such, there's a lot of interplay between the tokeniser +and the parser, which can get pretty frightening if you're not used to +it. + +As the parser understands a Perl program, it builds up a tree of +operations for the interpreter to perform during execution. The +routines which construct and link together the various operations are +to be found in F<op.c>, and will be examined later. + +=head2 Optimization + +Now the parsing stage is complete, and the finished tree represents the +operations that the Perl interpreter needs to perform to execute our +program. Next, Perl does a dry run over the tree looking for +optimisations: constant expressions such as C<3 + 4> will be computed +now, and the optimizer will also see if any multiple operations can be +replaced with a single one. For instance, to fetch the variable +C<$foo>, instead of grabbing the glob C<*foo> and looking at the scalar +component, the optimizer fiddles the op tree to use a function which +directly looks up the scalar in question. The main optimizer is C<peep> +in F<op.c>, and many ops have their own optimizing functions. + +=head2 Running + +Now we're finally ready to go: we have compiled Perl byte code, and all +that's left to do is run it. The actual execution is done by the +C<runops_standard> function in F<run.c>; more specifically, it's done +by these three innocent looking lines: + + while ((PL_op = PL_op->op_ppaddr(aTHX))) { + PERL_ASYNC_CHECK(); + } + +You may be more comfortable with the Perl version of that: + + PERL_ASYNC_CHECK() while $Perl::op = &{$Perl::op->{function}}; + +Well, maybe not. Anyway, each op contains a function pointer, which +stipulates the function which will actually carry out the operation. +This function will return the next op in the sequence - this allows for +things like C<if> which choose the next op dynamically at run time. The +C<PERL_ASYNC_CHECK> makes sure that things like signals interrupt +execution if required. + +The actual functions called are known as PP code, and they're spread +between four files: F<pp_hot.c> contains the "hot" code, which is most +often used and highly optimized, F<pp_sys.c> contains all the +system-specific functions, F<pp_ctl.c> contains the functions which +implement control structures (C<if>, C<while> and the like) and F<pp.c> +contains everything else. These are, if you like, the C code for Perl's +built-in functions and operators. + +Note that each C<pp_> function is expected to return a pointer to the +next op. Calls to perl subs (and eval blocks) are handled within the +same runops loop, and do not consume extra space on the C stack. For +example, C<pp_entersub> and C<pp_entertry> just push a C<CxSUB> or +C<CxEVAL> block struct onto the context stack which contain the address +of the op following the sub call or eval. They then return the first op +of that sub or eval block, and so execution continues of that sub or +block. Later, a C<pp_leavesub> or C<pp_leavetry> op pops the C<CxSUB> +or C<CxEVAL>, retrieves the return op from it, and returns it. + +=head2 Exception handing + +Perl's exception handing (i.e. C<die> etc.) is built on top of the +low-level C<setjmp()>/C<longjmp()> C-library functions. These basically +provide a way to capture the current PC and SP registers and later +restore them; i.e. a C<longjmp()> continues at the point in code where +a previous C<setjmp()> was done, with anything further up on the C +stack being lost. This is why code should always save values using +C<SAVE_FOO> rather than in auto variables. + +The perl core wraps C<setjmp()> etc in the macros C<JMPENV_PUSH> and +C<JMPENV_JUMP>. The basic rule of perl exceptions is that C<exit>, and +C<die> (in the absence of C<eval>) perform a C<JMPENV_JUMP(2)>, while +C<die> within C<eval> does a C<JMPENV_JUMP(3)>. + +At entry points to perl, such as C<perl_parse()>, C<perl_run()> and +C<call_sv(cv, G_EVAL)> each does a C<JMPENV_PUSH>, then enter a runops +loop or whatever, and handle possible exception returns. For a 2 +return, final cleanup is performed, such as popping stacks and calling +C<CHECK> or C<END> blocks. Amongst other things, this is how scope +cleanup still occurs during an C<exit>. + +If a C<die> can find a C<CxEVAL> block on the context stack, then the +stack is popped to that level and the return op in that block is +assigned to C<PL_restartop>; then a C<JMPENV_JUMP(3)> is performed. +This normally passes control back to the guard. In the case of +C<perl_run> and C<call_sv>, a non-null C<PL_restartop> triggers +re-entry to the runops loop. The is the normal way that C<die> or +C<croak> is handled within an C<eval>. + +Sometimes ops are executed within an inner runops loop, such as tie, +sort or overload code. In this case, something like + + sub FETCH { eval { die } } + +would cause a longjmp right back to the guard in C<perl_run>, popping +both runops loops, which is clearly incorrect. One way to avoid this is +for the tie code to do a C<JMPENV_PUSH> before executing C<FETCH> in +the inner runops loop, but for efficiency reasons, perl in fact just +sets a flag, using C<CATCH_SET(TRUE)>. The C<pp_require>, +C<pp_entereval> and C<pp_entertry> ops check this flag, and if true, +they call C<docatch>, which does a C<JMPENV_PUSH> and starts a new +runops level to execute the code, rather than doing it on the current +loop. + +As a further optimisation, on exit from the eval block in the C<FETCH>, +execution of the code following the block is still carried on in the +inner loop. When an exception is raised, C<docatch> compares the +C<JMPENV> level of the C<CxEVAL> with C<PL_top_env> and if they differ, +just re-throws the exception. In this way any inner loops get popped. + +Here's an example. + + 1: eval { tie @a, 'A' }; + 2: sub A::TIEARRAY { + 3: eval { die }; + 4: die; + 5: } + +To run this code, C<perl_run> is called, which does a C<JMPENV_PUSH> +then enters a runops loop. This loop executes the eval and tie ops on +line 1, with the eval pushing a C<CxEVAL> onto the context stack. + +The C<pp_tie> does a C<CATCH_SET(TRUE)>, then starts a second runops +loop to execute the body of C<TIEARRAY>. When it executes the entertry +op on line 3, C<CATCH_GET> is true, so C<pp_entertry> calls C<docatch> +which does a C<JMPENV_PUSH> and starts a third runops loop, which then +executes the die op. At this point the C call stack looks like this: + + Perl_pp_die + Perl_runops # third loop + S_docatch_body + S_docatch + Perl_pp_entertry + Perl_runops # second loop + S_call_body + Perl_call_sv + Perl_pp_tie + Perl_runops # first loop + S_run_body + perl_run + main + +and the context and data stacks, as shown by C<-Dstv>, look like: + + STACK 0: MAIN + CX 0: BLOCK => + CX 1: EVAL => AV() PV("A"\0) + retop=leave + STACK 1: MAGIC + CX 0: SUB => + retop=(null) + CX 1: EVAL => * + retop=nextstate + +The die pops the first C<CxEVAL> off the context stack, sets +C<PL_restartop> from it, does a C<JMPENV_JUMP(3)>, and control returns +to the top C<docatch>. This then starts another third-level runops +level, which executes the nextstate, pushmark and die ops on line 4. At +the point that the second C<pp_die> is called, the C call stack looks +exactly like that above, even though we are no longer within an inner +eval; this is because of the optimization mentioned earlier. However, +the context stack now looks like this, ie with the top CxEVAL popped: + + STACK 0: MAIN + CX 0: BLOCK => + CX 1: EVAL => AV() PV("A"\0) + retop=leave + STACK 1: MAGIC + CX 0: SUB => + retop=(null) + +The die on line 4 pops the context stack back down to the CxEVAL, +leaving it as: + + STACK 0: MAIN + CX 0: BLOCK => + +As usual, C<PL_restartop> is extracted from the C<CxEVAL>, and a +C<JMPENV_JUMP(3)> done, which pops the C stack back to the docatch: + + S_docatch + Perl_pp_entertry + Perl_runops # second loop + S_call_body + Perl_call_sv + Perl_pp_tie + Perl_runops # first loop + S_run_body + perl_run + main + +In this case, because the C<JMPENV> level recorded in the C<CxEVAL> +differs from the current one, C<docatch> just does a C<JMPENV_JUMP(3)> +and the C stack unwinds to: + + perl_run + main + +Because C<PL_restartop> is non-null, C<run_body> starts a new runops +loop and execution continues. + +=head2 INTERNAL VARIABLE TYPES + +You should by now have had a look at L<perlguts>, which tells you about +Perl's internal variable types: SVs, HVs, AVs and the rest. If not, do +that now. + +These variables are used not only to represent Perl-space variables, +but also any constants in the code, as well as some structures +completely internal to Perl. The symbol table, for instance, is an +ordinary Perl hash. Your code is represented by an SV as it's read into +the parser; any program files you call are opened via ordinary Perl +filehandles, and so on. + +The core L<Devel::Peek|Devel::Peek> module lets us examine SVs from a +Perl program. Let's see, for instance, how Perl treats the constant +C<"hello">. + + % perl -MDevel::Peek -e 'Dump("hello")' + 1 SV = PV(0xa041450) at 0xa04ecbc + 2 REFCNT = 1 + 3 FLAGS = (POK,READONLY,pPOK) + 4 PV = 0xa0484e0 "hello"\0 + 5 CUR = 5 + 6 LEN = 6 + +Reading C<Devel::Peek> output takes a bit of practise, so let's go +through it line by line. + +Line 1 tells us we're looking at an SV which lives at C<0xa04ecbc> in +memory. SVs themselves are very simple structures, but they contain a +pointer to a more complex structure. In this case, it's a PV, a +structure which holds a string value, at location C<0xa041450>. Line 2 +is the reference count; there are no other references to this data, so +it's 1. + +Line 3 are the flags for this SV - it's OK to use it as a PV, it's a +read-only SV (because it's a constant) and the data is a PV internally. +Next we've got the contents of the string, starting at location +C<0xa0484e0>. + +Line 5 gives us the current length of the string - note that this does +B<not> include the null terminator. Line 6 is not the length of the +string, but the length of the currently allocated buffer; as the string +grows, Perl automatically extends the available storage via a routine +called C<SvGROW>. + +You can get at any of these quantities from C very easily; just add +C<Sv> to the name of the field shown in the snippet, and you've got a +macro which will return the value: C<SvCUR(sv)> returns the current +length of the string, C<SvREFCOUNT(sv)> returns the reference count, +C<SvPV(sv, len)> returns the string itself with its length, and so on. +More macros to manipulate these properties can be found in L<perlguts>. + +Let's take an example of manipulating a PV, from C<sv_catpvn>, in +F<sv.c> + + 1 void + 2 Perl_sv_catpvn(pTHX_ register SV *sv, register const char *ptr, register STRLEN len) + 3 { + 4 STRLEN tlen; + 5 char *junk; + + 6 junk = SvPV_force(sv, tlen); + 7 SvGROW(sv, tlen + len + 1); + 8 if (ptr == junk) + 9 ptr = SvPVX(sv); + 10 Move(ptr,SvPVX(sv)+tlen,len,char); + 11 SvCUR(sv) += len; + 12 *SvEND(sv) = '\0'; + 13 (void)SvPOK_only_UTF8(sv); /* validate pointer */ + 14 SvTAINT(sv); + 15 } + +This is a function which adds a string, C<ptr>, of length C<len> onto +the end of the PV stored in C<sv>. The first thing we do in line 6 is +make sure that the SV B<has> a valid PV, by calling the C<SvPV_force> +macro to force a PV. As a side effect, C<tlen> gets set to the current +value of the PV, and the PV itself is returned to C<junk>. + +In line 7, we make sure that the SV will have enough room to +accommodate the old string, the new string and the null terminator. If +C<LEN> isn't big enough, C<SvGROW> will reallocate space for us. + +Now, if C<junk> is the same as the string we're trying to add, we can +grab the string directly from the SV; C<SvPVX> is the address of the PV +in the SV. + +Line 10 does the actual catenation: the C<Move> macro moves a chunk of +memory around: we move the string C<ptr> to the end of the PV - that's +the start of the PV plus its current length. We're moving C<len> bytes +of type C<char>. After doing so, we need to tell Perl we've extended +the string, by altering C<CUR> to reflect the new length. C<SvEND> is a +macro which gives us the end of the string, so that needs to be a +C<"\0">. + +Line 13 manipulates the flags; since we've changed the PV, any IV or NV +values will no longer be valid: if we have C<$a=10; $a.="6";> we don't +want to use the old IV of 10. C<SvPOK_only_utf8> is a special +UTF-8-aware version of C<SvPOK_only>, a macro which turns off the IOK +and NOK flags and turns on POK. The final C<SvTAINT> is a macro which +launders tainted data if taint mode is turned on. + +AVs and HVs are more complicated, but SVs are by far the most common +variable type being thrown around. Having seen something of how we +manipulate these, let's go on and look at how the op tree is +constructed. + +=head1 OP TREES + +First, what is the op tree, anyway? The op tree is the parsed +representation of your program, as we saw in our section on parsing, +and it's the sequence of operations that Perl goes through to execute +your program, as we saw in L</Running>. + +An op is a fundamental operation that Perl can perform: all the +built-in functions and operators are ops, and there are a series of ops +which deal with concepts the interpreter needs internally - entering +and leaving a block, ending a statement, fetching a variable, and so +on. + +The op tree is connected in two ways: you can imagine that there are +two "routes" through it, two orders in which you can traverse the tree. +First, parse order reflects how the parser understood the code, and +secondly, execution order tells perl what order to perform the +operations in. + +The easiest way to examine the op tree is to stop Perl after it has +finished parsing, and get it to dump out the tree. This is exactly what +the compiler backends L<B::Terse|B::Terse>, L<B::Concise|B::Concise> +and L<B::Debug|B::Debug> do. + +Let's have a look at how Perl sees C<$a = $b + $c>: + + % perl -MO=Terse -e '$a=$b+$c' + 1 LISTOP (0x8179888) leave + 2 OP (0x81798b0) enter + 3 COP (0x8179850) nextstate + 4 BINOP (0x8179828) sassign + 5 BINOP (0x8179800) add [1] + 6 UNOP (0x81796e0) null [15] + 7 SVOP (0x80fafe0) gvsv GV (0x80fa4cc) *b + 8 UNOP (0x81797e0) null [15] + 9 SVOP (0x8179700) gvsv GV (0x80efeb0) *c + 10 UNOP (0x816b4f0) null [15] + 11 SVOP (0x816dcf0) gvsv GV (0x80fa460) *a + +Let's start in the middle, at line 4. This is a BINOP, a binary +operator, which is at location C<0x8179828>. The specific operator in +question is C<sassign> - scalar assignment - and you can find the code +which implements it in the function C<pp_sassign> in F<pp_hot.c>. As a +binary operator, it has two children: the add operator, providing the +result of C<$b+$c>, is uppermost on line 5, and the left hand side is +on line 10. + +Line 10 is the null op: this does exactly nothing. What is that doing +there? If you see the null op, it's a sign that something has been +optimized away after parsing. As we mentioned in L</Optimization>, the +optimization stage sometimes converts two operations into one, for +example when fetching a scalar variable. When this happens, instead of +rewriting the op tree and cleaning up the dangling pointers, it's +easier just to replace the redundant operation with the null op. +Originally, the tree would have looked like this: + + 10 SVOP (0x816b4f0) rv2sv [15] + 11 SVOP (0x816dcf0) gv GV (0x80fa460) *a + +That is, fetch the C<a> entry from the main symbol table, and then look +at the scalar component of it: C<gvsv> (C<pp_gvsv> into F<pp_hot.c>) +happens to do both these things. + +The right hand side, starting at line 5 is similar to what we've just +seen: we have the C<add> op (C<pp_add> also in F<pp_hot.c>) add +together two C<gvsv>s. + +Now, what's this about? + + 1 LISTOP (0x8179888) leave + 2 OP (0x81798b0) enter + 3 COP (0x8179850) nextstate + +C<enter> and C<leave> are scoping ops, and their job is to perform any +housekeeping every time you enter and leave a block: lexical variables +are tidied up, unreferenced variables are destroyed, and so on. Every +program will have those first three lines: C<leave> is a list, and its +children are all the statements in the block. Statements are delimited +by C<nextstate>, so a block is a collection of C<nextstate> ops, with +the ops to be performed for each statement being the children of +C<nextstate>. C<enter> is a single op which functions as a marker. + +That's how Perl parsed the program, from top to bottom: + + Program + | + Statement + | + = + / \ + / \ + $a + + / \ + $b $c + +However, it's impossible to B<perform> the operations in this order: +you have to find the values of C<$b> and C<$c> before you add them +together, for instance. So, the other thread that runs through the op +tree is the execution order: each op has a field C<op_next> which +points to the next op to be run, so following these pointers tells us +how perl executes the code. We can traverse the tree in this order +using the C<exec> option to C<B::Terse>: + + % perl -MO=Terse,exec -e '$a=$b+$c' + 1 OP (0x8179928) enter + 2 COP (0x81798c8) nextstate + 3 SVOP (0x81796c8) gvsv GV (0x80fa4d4) *b + 4 SVOP (0x8179798) gvsv GV (0x80efeb0) *c + 5 BINOP (0x8179878) add [1] + 6 SVOP (0x816dd38) gvsv GV (0x80fa468) *a + 7 BINOP (0x81798a0) sassign + 8 LISTOP (0x8179900) leave + +This probably makes more sense for a human: enter a block, start a +statement. Get the values of C<$b> and C<$c>, and add them together. +Find C<$a>, and assign one to the other. Then leave. + +The way Perl builds up these op trees in the parsing process can be +unravelled by examining F<perly.y>, the YACC grammar. Let's take the +piece we need to construct the tree for C<$a = $b + $c> + + 1 term : term ASSIGNOP term + 2 { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); } + 3 | term ADDOP term + 4 { $$ = newBINOP($2, 0, scalar($1), scalar($3)); } + +If you're not used to reading BNF grammars, this is how it works: +You're fed certain things by the tokeniser, which generally end up in +upper case. Here, C<ADDOP>, is provided when the tokeniser sees C<+> in +your code. C<ASSIGNOP> is provided when C<=> is used for assigning. +These are "terminal symbols", because you can't get any simpler than +them. + +The grammar, lines one and three of the snippet above, tells you how to +build up more complex forms. These complex forms, "non-terminal +symbols" are generally placed in lower case. C<term> here is a +non-terminal symbol, representing a single expression. + +The grammar gives you the following rule: you can make the thing on the +left of the colon if you see all the things on the right in sequence. +This is called a "reduction", and the aim of parsing is to completely +reduce the input. There are several different ways you can perform a +reduction, separated by vertical bars: so, C<term> followed by C<=> +followed by C<term> makes a C<term>, and C<term> followed by C<+> +followed by C<term> can also make a C<term>. + +So, if you see two terms with an C<=> or C<+>, between them, you can +turn them into a single expression. When you do this, you execute the +code in the block on the next line: if you see C<=>, you'll do the code +in line 2. If you see C<+>, you'll do the code in line 4. It's this +code which contributes to the op tree. + + | term ADDOP term + { $$ = newBINOP($2, 0, scalar($1), scalar($3)); } + +What this does is creates a new binary op, and feeds it a number of +variables. The variables refer to the tokens: C<$1> is the first token +in the input, C<$2> the second, and so on - think regular expression +backreferences. C<$$> is the op returned from this reduction. So, we +call C<newBINOP> to create a new binary operator. The first parameter +to C<newBINOP>, a function in F<op.c>, is the op type. It's an addition +operator, so we want the type to be C<ADDOP>. We could specify this +directly, but it's right there as the second token in the input, so we +use C<$2>. The second parameter is the op's flags: 0 means "nothing +special". Then the things to add: the left and right hand side of our +expression, in scalar context. + +=head1 STACKS + +When perl executes something like C<addop>, how does it pass on its +results to the next op? The answer is, through the use of stacks. Perl +has a number of stacks to store things it's currently working on, and +we'll look at the three most important ones here. + +=head2 Argument stack + +Arguments are passed to PP code and returned from PP code using the +argument stack, C<ST>. The typical way to handle arguments is to pop +them off the stack, deal with them how you wish, and then push the +result back onto the stack. This is how, for instance, the cosine +operator works: + + NV value; + value = POPn; + value = Perl_cos(value); + XPUSHn(value); + +We'll see a more tricky example of this when we consider Perl's macros +below. C<POPn> gives you the NV (floating point value) of the top SV on +the stack: the C<$x> in C<cos($x)>. Then we compute the cosine, and +push the result back as an NV. The C<X> in C<XPUSHn> means that the +stack should be extended if necessary - it can't be necessary here, +because we know there's room for one more item on the stack, since +we've just removed one! The C<XPUSH*> macros at least guarantee safety. + +Alternatively, you can fiddle with the stack directly: C<SP> gives you +the first element in your portion of the stack, and C<TOP*> gives you +the top SV/IV/NV/etc. on the stack. So, for instance, to do unary +negation of an integer: + + SETi(-TOPi); + +Just set the integer value of the top stack entry to its negation. + +Argument stack manipulation in the core is exactly the same as it is in +XSUBs - see L<perlxstut>, L<perlxs> and L<perlguts> for a longer +description of the macros used in stack manipulation. + +=head2 Mark stack + +I say "your portion of the stack" above because PP code doesn't +necessarily get the whole stack to itself: if your function calls +another function, you'll only want to expose the arguments aimed for +the called function, and not (necessarily) let it get at your own data. +The way we do this is to have a "virtual" bottom-of-stack, exposed to +each function. The mark stack keeps bookmarks to locations in the +argument stack usable by each function. For instance, when dealing with +a tied variable, (internally, something with "P" magic) Perl has to +call methods for accesses to the tied variables. However, we need to +separate the arguments exposed to the method to the argument exposed to +the original function - the store or fetch or whatever it may be. +Here's roughly how the tied C<push> is implemented; see C<av_push> in +F<av.c>: + + 1 PUSHMARK(SP); + 2 EXTEND(SP,2); + 3 PUSHs(SvTIED_obj((SV*)av, mg)); + 4 PUSHs(val); + 5 PUTBACK; + 6 ENTER; + 7 call_method("PUSH", G_SCALAR|G_DISCARD); + 8 LEAVE; + +Let's examine the whole implementation, for practice: + + 1 PUSHMARK(SP); + +Push the current state of the stack pointer onto the mark stack. This +is so that when we've finished adding items to the argument stack, Perl +knows how many things we've added recently. + + 2 EXTEND(SP,2); + 3 PUSHs(SvTIED_obj((SV*)av, mg)); + 4 PUSHs(val); + +We're going to add two more items onto the argument stack: when you +have a tied array, the C<PUSH> subroutine receives the object and the +value to be pushed, and that's exactly what we have here - the tied +object, retrieved with C<SvTIED_obj>, and the value, the SV C<val>. + + 5 PUTBACK; + +Next we tell Perl to update the global stack pointer from our internal +variable: C<dSP> only gave us a local copy, not a reference to the +global. + + 6 ENTER; + 7 call_method("PUSH", G_SCALAR|G_DISCARD); + 8 LEAVE; + +C<ENTER> and C<LEAVE> localise a block of code - they make sure that +all variables are tidied up, everything that has been localised gets +its previous value returned, and so on. Think of them as the C<{> and +C<}> of a Perl block. + +To actually do the magic method call, we have to call a subroutine in +Perl space: C<call_method> takes care of that, and it's described in +L<perlcall>. We call the C<PUSH> method in scalar context, and we're +going to discard its return value. The call_method() function removes +the top element of the mark stack, so there is nothing for the caller +to clean up. + +=head2 Save stack + +C doesn't have a concept of local scope, so perl provides one. We've +seen that C<ENTER> and C<LEAVE> are used as scoping braces; the save +stack implements the C equivalent of, for example: + + { + local $foo = 42; + ... + } + +See L<perlguts/"Localizing Changes"> for how to use the save stack. + +=head1 MILLIONS OF MACROS + +One thing you'll notice about the Perl source is that it's full of +macros. Some have called the pervasive use of macros the hardest thing +to understand, others find it adds to clarity. Let's take an example, +the code which implements the addition operator: + + 1 PP(pp_add) + 2 { + 3 dSP; dATARGET; tryAMAGICbin(add,opASSIGN); + 4 { + 5 dPOPTOPnnrl_ul; + 6 SETn( left + right ); + 7 RETURN; + 8 } + 9 } + +Every line here (apart from the braces, of course) contains a macro. +The first line sets up the function declaration as Perl expects for PP +code; line 3 sets up variable declarations for the argument stack and +the target, the return value of the operation. Finally, it tries to see +if the addition operation is overloaded; if so, the appropriate +subroutine is called. + +Line 5 is another variable declaration - all variable declarations +start with C<d> - which pops from the top of the argument stack two NVs +(hence C<nn>) and puts them into the variables C<right> and C<left>, +hence the C<rl>. These are the two operands to the addition operator. +Next, we call C<SETn> to set the NV of the return value to the result +of adding the two values. This done, we return - the C<RETURN> macro +makes sure that our return value is properly handled, and we pass the +next operator to run back to the main run loop. + +Most of these macros are explained in L<perlapi>, and some of the more +important ones are explained in L<perlxs> as well. Pay special +attention to L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for +information on the C<[pad]THX_?> macros. + +=head1 FURTHER READING + +For more information on the Perl internals, please see the documents +listed at L<perl/Internals and C Language Interface>. diff --git a/Master/tlpkg/tlperl/lib/pods/perlintro.pod b/Master/tlpkg/tlperl/lib/pods/perlintro.pod index c47274bc646..2d0076a029d 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlintro.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlintro.pod @@ -22,6 +22,25 @@ Throughout this document you'll see references to other parts of the Perl documentation. You can read that documentation using the C<perldoc> command or whatever method you're using to read this document. +Throughout Perl's documentation, you'll find numerous examples intended +to help explain the discussed features. Please keep in mind that many +of them are code fragments rather than complete programs. + +These examples often reflect the style and preference of the author of +that piece of the documentation, and may be briefer than a corresponding +line of code in a real program. Except where otherwise noted, you +should assume that C<use strict> and C<use warnings> statements +appear earlier in the "program", and that any variables used have +already been declared, even if those declarations have been omitted +to make the example easier to read. + +Do note that the examples have been written by many different authors over +a period of several decades. Styles and techniques will therefore differ, +although some effort has been made to not vary styles too widely in the +same sections. Do not consider one style to be better than others - "There +Is More Than One Way Of Doing It" is one Perl's mottos. After all, in your +journey as a programmer, you are likely to encounter different styles. + =head2 What is Perl? Perl is a general-purpose programming language originally developed for diff --git a/Master/tlpkg/tlperl/lib/pods/perliol.pod b/Master/tlpkg/tlperl/lib/pods/perliol.pod index e81484772a7..0f71b93078f 100644 --- a/Master/tlpkg/tlperl/lib/pods/perliol.pod +++ b/Master/tlpkg/tlperl/lib/pods/perliol.pod @@ -526,11 +526,12 @@ passed to C<open>, otherwise it will be 1 if for example C<PerlIO_open> was called. In simple cases SvPV_nolen(*args) is the pathname to open. -Having said all that translation-only layers do not need to provide -C<Open()> at all, but rather leave the opening to a lower level layer -and wait to be "pushed". If a layer does provide C<Open()> it should -normally call the C<Open()> method of next layer down (if any) and -then push itself on top if that succeeds. +If a layer provides C<Open()> it should normally call the C<Open()> +method of next layer down (if any) and then push itself on top if that +succeeds. C<PerlIOBase_open> is provided to do exactly that, so in +most cases you don't have to write your own C<Open()> method. If this +method is not defined, other layers may have difficulty pushing +themselves on top of it during open. If C<PerlIO_push> was performed and open has failed, it must C<PerlIO_pop> itself, since if it's not, the layer won't be removed diff --git a/Master/tlpkg/tlperl/lib/pods/perlipc.pod b/Master/tlpkg/tlperl/lib/pods/perlipc.pod index 8d9ea9757d0..3009913147c 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlipc.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlipc.pod @@ -16,17 +16,19 @@ be called with an argument which is the name of the signal that triggered it. A signal may be generated intentionally from a particular keyboard sequence like control-C or control-Z, sent to you from another process, or triggered automatically by the kernel when -special events transpire, like a child process exiting, your process -running out of stack space, or hitting file size limit. +special events transpire, like a child process exiting, your own process +running out of stack space, or hitting a process file-size limit. For example, to trap an interrupt signal, set up a handler like this: + our $shucks; + sub catch_zap { - my $signame = shift; - $shucks++; - die "Somebody sent me a SIG$signame"; + my $signame = shift; + $shucks++; + die "Somebody sent me a SIG$signame"; } - $SIG{INT} = 'catch_zap'; # could fail in modules + $SIG{INT} = __PACKAGE__ . "::catch_zap"; $SIG{INT} = \&catch_zap; # best strategy Prior to Perl 5.7.3 it was necessary to do as little as you possibly @@ -39,59 +41,61 @@ dump - see L</Deferred Signals (Safe Signals)> below. The names of the signals are the ones listed out by C<kill -l> on your system, or you can retrieve them from the Config module. Set up an -@signame list indexed by number to get the name and a %signo table +@signame list indexed by number to get the name and a %signo hash table indexed by name to get the number: use Config; - defined $Config{sig_name} || die "No sigs?"; - foreach $name (split(' ', $Config{sig_name})) { - $signo{$name} = $i; - $signame[$i] = $name; - $i++; + defined($Config{sig_name}) || die "No sigs?"; + foreach $name (split(" ", $Config{sig_name})) { + $signo{$name} = $i; + $signame[$i] = $name; + $i++; } So to check whether signal 17 and SIGALRM were the same, do just this: print "signal #17 = $signame[17]\n"; if ($signo{ALRM}) { - print "SIGALRM is $signo{ALRM}\n"; + print "SIGALRM is $signo{ALRM}\n"; } -You may also choose to assign the strings C<'IGNORE'> or C<'DEFAULT'> as +You may also choose to assign the strings C<"IGNORE"> or C<"DEFAULT"> as the handler, in which case Perl will try to discard the signal or do the default thing. On most Unix platforms, the C<CHLD> (sometimes also known as C<CLD>) signal -has special behavior with respect to a value of C<'IGNORE'>. -Setting C<$SIG{CHLD}> to C<'IGNORE'> on such a platform has the effect of +has special behavior with respect to a value of C<"IGNORE">. +Setting C<$SIG{CHLD}> to C<"IGNORE"> on such a platform has the effect of not creating zombie processes when the parent process fails to C<wait()> -on its child processes (i.e. child processes are automatically reaped). -Calling C<wait()> with C<$SIG{CHLD}> set to C<'IGNORE'> usually returns +on its child processes (i.e., child processes are automatically reaped). +Calling C<wait()> with C<$SIG{CHLD}> set to C<"IGNORE"> usually returns C<-1> on such platforms. -Some signals can be neither trapped nor ignored, such as -the KILL and STOP (but not the TSTP) signals. One strategy for -temporarily ignoring signals is to use a local() statement, which will be -automatically restored once your block is exited. (Remember that local() -values are "inherited" by functions called from within that block.) +Some signals can be neither trapped nor ignored, such as the KILL and STOP +(but not the TSTP) signals. One strategy for temporarily ignoring signals +is to use a local() on that hash element, automatically restoring a +previous value once your block is exited. Remember that values created by +the dynamically-scoped local() are "inherited" by functions called from +within their caller's scope. sub precious { - local $SIG{INT} = 'IGNORE'; - &more_functions; + local $SIG{INT} = "IGNORE"; + more_functions(); } sub more_functions { - # interrupts still ignored, for now... + # interrupts still ignored, for now... } Sending a signal to a negative process ID means that you send the signal -to the entire Unix process-group. This code sends a hang-up signal to all -processes in the current process group (and sets $SIG{HUP} to IGNORE so -it doesn't kill itself): +to the entire Unix process group. This code sends a hang-up signal to all +processes in the current process group, and also sets $SIG{HUP} to C<"IGNORE"> +so it doesn't kill itself: + # block scope for local { - local $SIG{HUP} = 'IGNORE'; - kill HUP => -$$; - # snazzy writing of: kill('HUP', -$$) + local $SIG{HUP} = "IGNORE"; + kill HUP => -$$; + # snazzy writing of: kill("HUP", -$$) } Another interesting signal to send is signal number zero. This doesn't @@ -99,7 +103,7 @@ actually affect a child process, but instead checks whether it's alive or has changed its UID. unless (kill 0 => $kid_pid) { - warn "something wicked happened to $kid_pid"; + warn "something wicked happened to $kid_pid"; } When directed at a process whose UID is not identical to that @@ -107,8 +111,8 @@ of the sending process, signal number zero may fail because you lack permission to send the signal, even though the process is alive. You may be able to determine the cause of failure using C<%!>. - unless (kill 0 => $pid or $!{EPERM}) { - warn "$pid looks dead"; + unless (kill(0 => $pid) || $!{EPERM}) { + warn "$pid looks dead"; } You might also want to employ anonymous functions for simple signal @@ -119,16 +123,16 @@ handlers: But that will be problematic for the more complicated handlers that need to reinstall themselves. Because Perl's signal mechanism is currently based on the signal(3) function from the C library, you may sometimes be so -unfortunate as to run on systems where that function is "broken", that +unfortunate as to run on systems where that function is "broken"; that is, it behaves in the old unreliable SysV way rather than the newer, more reasonable BSD and POSIX fashion. So you'll see defensive people writing signal handlers like this: sub REAPER { - $waitedpid = wait; - # loathe SysV: it makes us not only reinstate - # the handler, but place it after the wait - $SIG{CHLD} = \&REAPER; + $waitedpid = wait; + # loathe SysV: it makes us not only reinstate + # the handler, but place it after the wait + $SIG{CHLD} = \&REAPER; } $SIG{CHLD} = \&REAPER; # now do something that forks... @@ -137,26 +141,26 @@ or better still: use POSIX ":sys_wait_h"; sub REAPER { - my $child; - # If a second child dies while in the signal handler caused by the - # first death, we won't get another signal. So must loop here else - # we will leave the unreaped child as a zombie. And the next time - # two children die we get another zombie. And so on. - while (($child = waitpid(-1,WNOHANG)) > 0) { - $Kid_Status{$child} = $?; - } - $SIG{CHLD} = \&REAPER; # still loathe SysV + my $child; + # If a second child dies while in the signal handler caused by the + # first death, we won't get another signal. So must loop here else + # we will leave the unreaped child as a zombie. And the next time + # two children die we get another zombie. And so on. + while (($child = waitpid(-1, WNOHANG)) > 0) { + $Kid_Status{$child} = $?; + } + $SIG{CHLD} = \&REAPER; # still loathe SysV } $SIG{CHLD} = \&REAPER; # do something that forks... -Note: qx(), system() and some modules for calling external commands do a -fork() and wait() for the result. Thus, your signal handler (REAPER in the -example) will be called. Since wait() was already called by system() or qx() -the wait() in the signal handler will not see any more zombies and therefore -block. +Be careful: qx(), system(), and some modules for calling external commands +do a fork(), then wait() for the result. Thus, your signal handler +(C<&REAPER> in the example) will be called. Because wait() was already +called by system() or qx(), the wait() in the signal handler will see no +more zombies and will therefore block. -The best way to prevent this issue is to use waitpid, as in the following +The best way to prevent this issue is to use waitpid(), as in the following example: use POSIX ":sys_wait_h"; # for nonblocking read @@ -165,7 +169,7 @@ example: $SIG{CHLD} = sub { # don't change $! and $? outside handler - local ($!,$?); + local ($!, $?); my $pid = waitpid(-1, WNOHANG); return if $pid == -1; return unless defined $children{$pid}; @@ -175,11 +179,12 @@ example: while (1) { my $pid = fork(); + die "cannot fork" unless defined $pid; if ($pid == 0) { # ... exit 0; } else { - $children{$pid}=1; + $children{$pid}=1; # ... system($command); # ... @@ -196,13 +201,15 @@ using longjmp() or throw() in other languages. Here's an example: + my $ALARM_EXCEPTION = "alarm clock restart"; eval { - local $SIG{ALRM} = sub { die "alarm clock restart" }; + local $SIG{ALRM} = sub { die $ALARM_EXCEPTION }; alarm 10; - flock(FH, 2); # blocking write lock + flock(FH, 2) # blocking write lock + || die "cannot flock: $!"; alarm 0; }; - if ($@ and $@ !~ /alarm clock restart/) { die } + if ($@ && $@ !~ quotemeta($ALARM_EXCEPTION)) { die } If the operation being timed out is system() or qx(), this technique is liable to generate zombies. If this matters to you, you'll @@ -219,21 +226,21 @@ A process that usually starts when the system boots and shuts down when the system is shut down is called a daemon (Disk And Execution MONitor). If a daemon process has a configuration file which is modified after the process has been started, there should be a way to -tell that process to re-read its configuration file, without stopping -the process. Many daemons provide this mechanism using the C<SIGHUP> -signal handler. When you want to tell the daemon to re-read the file -you simply send it the C<SIGHUP> signal. +tell that process to reread its configuration file without stopping +the process. Many daemons provide this mechanism using a C<SIGHUP> +signal handler. When you want to tell the daemon to reread the file, +simply send it the C<SIGHUP> signal. Not all platforms automatically reinstall their (native) signal handlers after a signal delivery. This means that the handler works -only the first time the signal is sent. The solution to this problem -is to use C<POSIX> signal handlers if available, their behaviour +the first time the signal is sent, only. The solution to this problem +is to use C<POSIX> signal handlers if available; their behavior is well-defined. The following example implements a simple daemon, which restarts itself every time the C<SIGHUP> signal is received. The actual code is -located in the subroutine C<code()>, which simply prints some debug -info to show that it works and should be replaced with the real code. +located in the subroutine C<code()>, which just prints some debugging +info to show that it works; it should be replaced with the real code. #!/usr/bin/perl -w @@ -242,23 +249,23 @@ info to show that it works and should be replaced with the real code. use File::Basename (); use File::Spec::Functions; - $|=1; + $| = 1; # make the daemon cross-platform, so exec always calls the script # itself with the right path, no matter how the script was invoked. my $script = File::Basename::basename($0); - my $SELF = catfile $FindBin::Bin, $script; + my $SELF = catfile($FindBin::Bin, $script); # POSIX unmasks the sigprocmask properly my $sigset = POSIX::SigSet->new(); - my $action = POSIX::SigAction->new('sigHUP_handler', + my $action = POSIX::SigAction->new("sigHUP_handler", $sigset, &POSIX::SA_NODEFER); POSIX::sigaction(&POSIX::SIGHUP, $action); sub sigHUP_handler { print "got SIGHUP\n"; - exec($SELF, @ARGV) or die "Couldn't restart: $!\n"; + exec($SELF, @ARGV) || die "$0: couldn't restart: $!"; } code(); @@ -266,80 +273,24 @@ info to show that it works and should be replaced with the real code. sub code { print "PID: $$\n"; print "ARGV: @ARGV\n"; - my $c = 0; - while (++$c) { + my $count = 0; + while (++$count) { sleep 2; - print "$c\n"; + print "$count\n"; } } - __END__ - - -=head1 Named Pipes - -A named pipe (often referred to as a FIFO) is an old Unix IPC -mechanism for processes communicating on the same machine. It works -just like a regular, connected anonymous pipes, except that the -processes rendezvous using a filename and don't have to be related. - -To create a named pipe, use the C<POSIX::mkfifo()> function. - - use POSIX qw(mkfifo); - mkfifo($path, 0700) or die "mkfifo $path failed: $!"; - -You can also use the Unix command mknod(1) or on some -systems, mkfifo(1). These may not be in your normal path. - - # system return val is backwards, so && not || - # - $ENV{PATH} .= ":/etc:/usr/etc"; - if ( system('mknod', $path, 'p') - && system('mkfifo', $path) ) - { - die "mk{nod,fifo} $path failed"; - } -A fifo is convenient when you want to connect a process to an unrelated -one. When you open a fifo, the program will block until there's something -on the other end. - -For example, let's say you'd like to have your F<.signature> file be a -named pipe that has a Perl program on the other end. Now every time any -program (like a mailer, news reader, finger program, etc.) tries to read -from that file, the reading program will block and your program will -supply the new signature. We'll use the pipe-checking file test B<-p> -to find out whether anyone (or anything) has accidentally removed our fifo. - - chdir; # go home - $FIFO = '.signature'; - - while (1) { - unless (-p $FIFO) { - unlink $FIFO; - require POSIX; - POSIX::mkfifo($FIFO, 0700) - or die "can't mkfifo $FIFO: $!"; - } - - # next line blocks until there's a reader - open (FIFO, "> $FIFO") || die "can't write $FIFO: $!"; - print FIFO "John Smith (smith\@host.org)\n", `fortune -s`; - close FIFO; - sleep 2; # to avoid dup signals - } - =head2 Deferred Signals (Safe Signals) -In Perls before Perl 5.7.3 by installing Perl code to deal with -signals, you were exposing yourself to danger from two things. First, -few system library functions are re-entrant. If the signal interrupts -while Perl is executing one function (like malloc(3) or printf(3)), -and your signal handler then calls the same function again, you could -get unpredictable behavior--often, a core dump. Second, Perl isn't -itself re-entrant at the lowest levels. If the signal interrupts Perl -while Perl is changing its own internal data structures, similarly -unpredictable behaviour may result. +Before Perl 5.7.3, installing Perl code to deal with signals exposed you to +danger from two things. First, few system library functions are +re-entrant. If the signal interrupts while Perl is executing one function +(like malloc(3) or printf(3)), and your signal handler then calls the same +function again, you could get unpredictable behavior--often, a core dump. +Second, Perl isn't itself re-entrant at the lowest levels. If the signal +interrupts Perl while Perl is changing its own internal data structures, +similarly unpredictable behavior may result. There were two things you could do, knowing this: be paranoid or be pragmatic. The paranoid approach was to do as little as possible in your @@ -352,30 +303,28 @@ The pragmatic approach was to say "I know the risks, but prefer the convenience", and to do anything you wanted in your signal handler, and be prepared to clean up core dumps now and again. -Perl 5.7.3 and later avoid these problems by "deferring" signals. -That is, when the signal is delivered to the process by -the system (to the C code that implements Perl) a flag is set, and the -handler returns immediately. Then at strategic "safe" points in the -Perl interpreter (e.g. when it is about to execute a new opcode) the -flags are checked and the Perl level handler from %SIG is -executed. The "deferred" scheme allows much more flexibility in the -coding of signal handler as we know Perl interpreter is in a safe -state, and that we are not in a system library function when the -handler is called. However the implementation does differ from -previous Perls in the following ways: +Perl 5.7.3 and later avoid these problems by "deferring" signals. That is, +when the signal is delivered to the process by the system (to the C code +that implements Perl) a flag is set, and the handler returns immediately. +Then at strategic "safe" points in the Perl interpreter (e.g. when it is +about to execute a new opcode) the flags are checked and the Perl level +handler from %SIG is executed. The "deferred" scheme allows much more +flexibility in the coding of signal handlers as we know the Perl +interpreter is in a safe state, and that we are not in a system library function when the handler is called. However the implementation does +differ from previous Perls in the following ways: =over 4 =item Long-running opcodes -As the Perl interpreter only looks at the signal flags when it is about +As the Perl interpreter looks at signal flags only when it is about to execute a new opcode, a signal that arrives during a long-running opcode (e.g. a regular expression operation on a very large string) will not be seen until the current opcode completes. -N.B. If a signal of any given type fires multiple times during an opcode +If a signal of any given type fires multiple times during an opcode (such as from a fine-grained timer), the handler for that signal will -only be called once after the opcode completes, and all the other +be called only once, after the opcode completes; all other instances will be discarded. Furthermore, if your system's signal queue gets flooded to the point that there are signals that have been raised but not yet caught (and thus not deferred) at the time an opcode @@ -387,31 +336,37 @@ raised but not yet caught. Do not depend on the behaviors described in this paragraph as they are side effects of the current implementation and may change in future versions of Perl. - =item Interrupting IO -When a signal is delivered (e.g. INT control-C) the operating system -breaks into IO operations like C<read> (used to implement Perls -E<lt>E<gt> operator). On older Perls the handler was called -immediately (and as C<read> is not "unsafe" this worked well). With -the "deferred" scheme the handler is not called immediately, and if -Perl is using system's C<stdio> library that library may re-start the -C<read> without returning to Perl and giving it a chance to call the -%SIG handler. If this happens on your system the solution is to use -C<:perlio> layer to do IO - at least on those handles which you want -to be able to break into with signals. (The C<:perlio> layer checks -the signal flags and calls %SIG handlers before resuming IO operation.) - -Note that the default in Perl 5.7.3 and later is to automatically use +When a signal is delivered (e.g., SIGINT from a control-C) the operating +system breaks into IO operations like I<read>(2), which is used to +implement Perl's readline() function, the C<< <> >> operator. On older +Perls the handler was called immediately (and as C<read> is not "unsafe", +this worked well). With the "deferred" scheme the handler is I<not> called +immediately, and if Perl is using the system's C<stdio> library that +library may restart the C<read> without returning to Perl to give it a +chance to call the %SIG handler. If this happens on your system the +solution is to use the C<:perlio> layer to do IO--at least on those handles +that you want to be able to break into with signals. (The C<:perlio> layer +checks the signal flags and calls %SIG handlers before resuming IO +operation.) + +The default in Perl 5.7.3 and later is to automatically use the C<:perlio> layer. -Note that some networking library functions like gethostbyname() are -known to have their own implementations of timeouts which may conflict -with your timeouts. If you are having problems with such functions, -you can try using the POSIX sigaction() function, which bypasses the -Perl safe signals (note that this means subjecting yourself to -possible memory corruption, as described above). Instead of setting -C<$SIG{ALRM}>: +Note that it is not advisable to access a file handle within a signal +handler where that signal has interrupted an I/O operation on that same +handle. While perl will at least try hard not to crash, there are no +guarantees of data integrity; for example, some data might get dropped or +written twice. + +Some networking library functions like gethostbyname() are known to have +their own implementations of timeouts which may conflict with your +timeouts. If you have problems with such functions, try using the POSIX +sigaction() function, which bypasses Perl safe signals. Be warned that +this does subject you to possible memory corruption, as described above. + +Instead of setting C<$SIG{ALRM}>: local $SIG{ALRM} = sub { die "alarm" }; @@ -420,11 +375,11 @@ try something like the following: use POSIX qw(SIGALRM); POSIX::sigaction(SIGALRM, POSIX::SigAction->new(sub { die "alarm" })) - or die "Error setting SIGALRM handler: $!\n"; + || die "Error setting SIGALRM handler: $!\n"; Another way to disable the safe signal behavior locally is to use -the C<Perl::Unsafe::Signals> module from CPAN (which will affect -all signals). +the C<Perl::Unsafe::Signals> module from CPAN, which affects +all signals. =item Restartable system calls @@ -436,33 +391,87 @@ Perl 5.7.3 and later do I<not> use SA_RESTART. Consequently, restartable system calls can fail (with $! set to C<EINTR>) in places where they previously would have succeeded. -Note that the default C<:perlio> layer will retry C<read>, C<write> -and C<close> as described above and that interrupted C<wait> and +The default C<:perlio> layer retries C<read>, C<write> +and C<close> as described above; interrupted C<wait> and C<waitpid> calls will always be retried. =item Signals as "faults" -Certain signals, e.g. SEGV, ILL, and BUS, are generated as a result of -virtual memory or other "faults". These are normally fatal and there is -little a Perl-level handler can do with them, so Perl now delivers them +Certain signals like SEGV, ILL, and BUS are generated by virtual memory +addressing errors and similar "faults". These are normally fatal: there is +little a Perl-level handler can do with them. So Perl now delivers them immediately rather than attempting to defer them. =item Signals triggered by operating system state On some operating systems certain signal handlers are supposed to "do -something" before returning. One example can be CHLD or CLD which +something" before returning. One example can be CHLD or CLD, which indicates a child process has completed. On some operating systems the signal handler is expected to C<wait> for the completed child process. On such systems the deferred signal scheme will not work for -those signals (it does not do the C<wait>). Again the failure will -look like a loop as the operating system will re-issue the signal as -there are un-waited-for completed child processes. +those signals: it does not do the C<wait>. Again the failure will +look like a loop as the operating system will reissue the signal because +there are completed child processes that have not yet been C<wait>ed for. =back -If you want the old signal behaviour back regardless of possible +If you want the old signal behavior back despite possible memory corruption, set the environment variable C<PERL_SIGNALS> to -C<"unsafe"> (a new feature since Perl 5.8.1). +C<"unsafe">. This feature first appeared in Perl 5.8.1. + +=head1 Named Pipes + +A named pipe (often referred to as a FIFO) is an old Unix IPC +mechanism for processes communicating on the same machine. It works +just like regular anonymous pipes, except that the +processes rendezvous using a filename and need not be related. + +To create a named pipe, use the C<POSIX::mkfifo()> function. + + use POSIX qw(mkfifo); + mkfifo($path, 0700) || die "mkfifo $path failed: $!"; + +You can also use the Unix command mknod(1), or on some +systems, mkfifo(1). These may not be in your normal path, though. + + # system return val is backwards, so && not || + # + $ENV{PATH} .= ":/etc:/usr/etc"; + if ( system("mknod", $path, "p") + && system("mkfifo", $path) ) + { + die "mk{nod,fifo} $path failed"; + } + + +A fifo is convenient when you want to connect a process to an unrelated +one. When you open a fifo, the program will block until there's something +on the other end. + +For example, let's say you'd like to have your F<.signature> file be a +named pipe that has a Perl program on the other end. Now every time any +program (like a mailer, news reader, finger program, etc.) tries to read +from that file, the reading program will read the new signature from your +program. We'll use the pipe-checking file-test operator, B<-p>, to find +out whether anyone (or anything) has accidentally removed our fifo. + + chdir(); # go home + my $FIFO = ".signature"; + + while (1) { + unless (-p $FIFO) { + unlink $FIFO; # discard any failure, will catch later + require POSIX; # delayed loading of heavy module + POSIX::mkfifo($FIFO, 0700) + || die "can't mkfifo $FIFO: $!"; + } + + # next line blocks till there's a reader + open (FIFO, "> $FIFO") || die "can't open $FIFO: $!"; + print FIFO "John Smith (smith\@host.org)\n", `fortune -s`; + close(FIFO) || die "can't close $FIFO: $!"; + sleep 2; # to avoid dup signals + } =head1 Using open() for IPC @@ -472,28 +481,27 @@ symbol to the second argument to open(). Here's how to start something up in a child process you intend to write to: open(SPOOLER, "| cat -v | lpr -h 2>/dev/null") - || die "can't fork: $!"; + || die "can't fork: $!"; local $SIG{PIPE} = sub { die "spooler pipe broke" }; print SPOOLER "stuff\n"; - close SPOOLER || die "bad spool: $! $?"; + close SPOOLER || die "bad spool: $! $?"; And here's how to start up a child process you intend to read from: open(STATUS, "netstat -an 2>&1 |") - || die "can't fork: $!"; + || die "can't fork: $!"; while (<STATUS>) { - next if /^(tcp|udp)/; - print; + next if /^(tcp|udp)/; + print; } - close STATUS || die "bad netstat: $! $?"; + close STATUS || die "bad netstat: $! $?"; -If one can be sure that a particular program is a Perl script that is -expecting filenames in @ARGV, the clever programmer can write something -like this: +If one can be sure that a particular program is a Perl script expecting +filenames in @ARGV, the clever programmer can write something like this: % program f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile -and irrespective of which shell it's called from, the Perl program will +and no matter which sort of shell it's called from, the Perl program will read from the file F<f1>, the process F<cmd1>, standard input (F<tmpfile> in this case), the F<f2> file, the F<cmd2> command, and finally the F<f3> file. Pretty nifty, eh? @@ -502,36 +510,38 @@ You might notice that you could use backticks for much the same effect as opening a pipe for reading: print grep { !/^(tcp|udp)/ } `netstat -an 2>&1`; - die "bad netstat" if $?; + die "bad netstatus ($?)" if $?; While this is true on the surface, it's much more efficient to process the file one line or record at a time because then you don't have to read the whole thing into memory at once. It also gives you finer control of the -whole process, letting you to kill off the child process early if you'd -like. +whole process, letting you kill off the child process early if you'd like. -Be careful to check both the open() and the close() return values. If +Be careful to check the return values from both open() and close(). If you're I<writing> to a pipe, you should also trap SIGPIPE. Otherwise, think of what happens when you start up a pipe to a command that doesn't exist: the open() will in all likelihood succeed (it only reflects the fork()'s success), but then your output will fail--spectacularly. Perl -can't know whether the command worked because your command is actually +can't know whether the command worked, because your command is actually running in a separate process whose exec() might have failed. Therefore, -while readers of bogus commands return just a quick end of file, writers -to bogus command will trigger a signal they'd better be prepared to -handle. Consider: +while readers of bogus commands return just a quick EOF, writers +to bogus commands will get hit with a signal, which they'd best be prepared +to handle. Consider: - open(FH, "|bogus") or die "can't fork: $!"; - print FH "bang\n" or die "can't write: $!"; - close FH or die "can't close: $!"; + open(FH, "|bogus") || die "can't fork: $!"; + print FH "bang\n"; # neither necessary nor sufficient + # to check print retval! + close(FH) || die "can't close: $!"; -That won't blow up until the close, and it will blow up with a SIGPIPE. -To catch it, you could use this: +The reason for not checking the return value from print() is because of +pipe buffering; physical writes are delayed. That won't blow up until the +close, and it will blow up with a SIGPIPE. To catch it, you could use +this: - $SIG{PIPE} = 'IGNORE'; - open(FH, "|bogus") or die "can't fork: $!"; - print FH "bang\n" or die "can't write: $!"; - close FH or die "can't close: status=$?"; + $SIG{PIPE} = "IGNORE"; + open(FH, "|bogus") || die "can't fork: $!"; + print FH "bang\n"; + close(FH) || die "can't close: status=$?"; =head2 Filehandles @@ -550,76 +560,78 @@ You can run a command in the background with: The command's STDOUT and STDERR (and possibly STDIN, depending on your shell) will be the same as the parent's. You won't need to catch -SIGCHLD because of the double-fork taking place (see below for more -details). +SIGCHLD because of the double-fork taking place; see below for details. =head2 Complete Dissociation of Child from Parent In some cases (starting server processes, for instance) you'll want to completely dissociate the child process from the parent. This is -often called daemonization. A well behaved daemon will also chdir() -to the root directory (so it doesn't prevent unmounting the filesystem -containing the directory from which it was launched) and redirect its -standard file descriptors from and to F</dev/null> (so that random -output doesn't wind up on the user's terminal). +often called daemonization. A well-behaved daemon will also chdir() +to the root directory so it doesn't prevent unmounting the filesystem +containing the directory from which it was launched, and redirect its +standard file descriptors from and to F</dev/null> so that random +output doesn't wind up on the user's terminal. - use POSIX 'setsid'; + use POSIX "setsid"; sub daemonize { - chdir '/' or die "Can't chdir to /: $!"; - open STDIN, '/dev/null' or die "Can't read /dev/null: $!"; - open STDOUT, '>/dev/null' - or die "Can't write to /dev/null: $!"; - defined(my $pid = fork) or die "Can't fork: $!"; - exit if $pid; - die "Can't start a new session: $!" if setsid == -1; - open STDERR, '>&STDOUT' or die "Can't dup stdout: $!"; + chdir("/") || die "can't chdir to /: $!"; + open(STDIN, "< /dev/null") || die "can't read /dev/null: $!"; + open(STDOUT, "> /dev/null") || die "can't write to /dev/null: $!"; + defined(my $pid = fork()) || die "can't fork: $!"; + exit if $pid; # non-zero now means I am the parent + (setsid() != -1) || die "Can't start a new session: $!" + open(STDERR, ">&STDOUT") || die "can't dup stdout: $!"; } -The fork() has to come before the setsid() to ensure that you aren't a -process group leader (the setsid() will fail if you are). If your +The fork() has to come before the setsid() to ensure you aren't a +process group leader; the setsid() will fail if you are. If your system doesn't have the setsid() function, open F</dev/tty> and use the C<TIOCNOTTY> ioctl() on it instead. See tty(4) for details. -Non-Unix users should check their Your_OS::Process module for other -solutions. +Non-Unix users should check their C<< I<Your_OS>::Process >> module for +other possible solutions. =head2 Safe Pipe Opens Another interesting approach to IPC is making your single program go -multiprocess and communicate between (or even amongst) yourselves. The +multiprocess and communicate between--or even amongst--yourselves. The open() function will accept a file argument of either C<"-|"> or C<"|-"> to do a very interesting thing: it forks a child connected to the filehandle you've opened. The child is running the same program as the parent. This is useful for safely opening a file when running under an assumed UID or GID, for example. If you open a pipe I<to> minus, you can -write to the filehandle you opened and your kid will find it in his +write to the filehandle you opened and your kid will find it in I<his> STDIN. If you open a pipe I<from> minus, you can read from the filehandle -you opened whatever your kid writes to his STDOUT. +you opened whatever your kid writes to I<his> STDOUT. - use English '-no_match_vars'; - my $sleep_count = 0; + use English qw[ -no_match_vars ]; + my $PRECIOUS = "/path/to/some/safe/file"; + my $sleep_count; + my $pid; do { - $pid = open(KID_TO_WRITE, "|-"); - unless (defined $pid) { - warn "cannot fork: $!"; - die "bailing out" if $sleep_count++ > 6; - sleep 10; - } + $pid = open(KID_TO_WRITE, "|-"); + unless (defined $pid) { + warn "cannot fork: $!"; + die "bailing out" if $sleep_count++ > 6; + sleep 10; + } } until defined $pid; - if ($pid) { # parent - print KID_TO_WRITE @some_data; - close(KID_TO_WRITE) || warn "kid exited $?"; - } else { # child - ($EUID, $EGID) = ($UID, $GID); # suid progs only - open (FILE, "> /safe/file") - || die "can't open /safe/file: $!"; - while (<STDIN>) { - print FILE; # child's STDIN is parent's KID_TO_WRITE - } - exit; # don't forget this + if ($pid) { # I am the parent + print KID_TO_WRITE @some_data; + close(KID_TO_WRITE) || warn "kid exited $?"; + } else { # I am the child + # drop permissions in setuid and/or setgid programs: + ($EUID, $EGID) = ($UID, $GID); + open (OUTFILE, "> $PRECIOUS") + || die "can't open $PRECIOUS: $!"; + while (<STDIN>) { + print OUTFILE; # child's STDIN is parent's KID_TO_WRITE + } + close(OUTFILE) || die "can't close $PRECIOUS: $!"; + exit(0); # don't forget this!! } Another common use for this construct is when you need to execute @@ -630,45 +642,43 @@ your arguments. Instead, use lower-level control to call exec() directly. Here's a safe backtick or pipe open for read: - # add error processing as above - $pid = open(KID_TO_READ, "-|"); + my $pid = open(KID_TO_READ, "-|"); + defined($pid) || die "can't fork: $!"; - if ($pid) { # parent - while (<KID_TO_READ>) { - # do something interesting - } - close(KID_TO_READ) || warn "kid exited $?"; + if ($pid) { # parent + while (<KID_TO_READ>) { + # do something interesting + } + close(KID_TO_READ) || warn "kid exited $?"; - } else { # child - ($EUID, $EGID) = ($UID, $GID); # suid only - exec($program, @options, @args) - || die "can't exec program: $!"; - # NOTREACHED + } else { # child + ($EUID, $EGID) = ($UID, $GID); # suid only + exec($program, @options, @args) + || die "can't exec program: $!"; + # NOTREACHED } - And here's a safe pipe open for writing: - # add error processing as above - $pid = open(KID_TO_WRITE, "|-"); + my $pid = open(KID_TO_WRITE, "|-"); + defined($pid) || die "can't fork: $!"; + $SIG{PIPE} = sub { die "whoops, $program pipe broke" }; - if ($pid) { # parent - for (@data) { - print KID_TO_WRITE; - } - close(KID_TO_WRITE) || warn "kid exited $?"; - - } else { # child - ($EUID, $EGID) = ($UID, $GID); - exec($program, @options, @args) - || die "can't exec program: $!"; - # NOTREACHED + if ($pid) { # parent + print KID_TO_WRITE @data; + close(KID_TO_WRITE) || warn "kid exited $?"; + + } else { # child + ($EUID, $EGID) = ($UID, $GID); + exec($program, @options, @args) + || die "can't exec program: $!"; + # NOTREACHED } It is very easy to dead-lock a process using this form of open(), or -indeed any use of pipe() and multiple sub-processes. The above -example is 'safe' because it is simple and calls exec(). See +indeed with any use of pipe() with multiple subprocesses. The +example above is "safe" because it is simple and calls exec(). See L</"Avoiding Pipe Deadlocks"> for general safety principles, but there are extra gotchas with Safe Pipe Opens. @@ -676,194 +686,218 @@ In particular, if you opened the pipe using C<open FH, "|-">, then you cannot simply use close() in the parent process to close an unwanted writer. Consider this code: - $pid = open WRITER, "|-"; - defined $pid or die "fork failed; $!"; + my $pid = open(WRITER, "|-"); # fork open a kid + defined($pid) || die "first fork failed: $!"; if ($pid) { if (my $sub_pid = fork()) { - close WRITER; - # do something else... + defined($sub_pid) || die "second fork failed: $!"; + close(WRITER) || die "couldn't close WRITER: $!"; + # now do something else... } else { - # write to WRITER... - exit; + # first write to WRITER + # ... + # then when finished + close(WRITER) || die "couldn't close WRITER: $!"; + exit(0); } } else { - # do something with STDIN... - exit; + # first do something with STDIN, then + exit(0); } -In the above, the true parent does not want to write to the WRITER +In the example above, the true parent does not want to write to the WRITER filehandle, so it closes it. However, because WRITER was opened using -C<open FH, "|-">, it has a special behaviour: closing it will call -waitpid() (see L<perlfunc/waitpid>), which waits for the sub-process +C<open FH, "|-">, it has a special behavior: closing it calls +waitpid() (see L<perlfunc/waitpid>), which waits for the subprocess to exit. If the child process ends up waiting for something happening -in the section marked "do something else", then you have a deadlock. +in the section marked "do something else", you have deadlock. -This can also be a problem with intermediate sub-processes in more +This can also be a problem with intermediate subprocesses in more complicated code, which will call waitpid() on all open filehandles -during global destruction; in no predictable order. +during global destruction--in no predictable order. To solve this, you must manually use pipe(), fork(), and the form of -open() which sets one file descriptor to another, as below: +open() which sets one file descriptor to another, as shown below: - pipe(READER, WRITER); + pipe(READER, WRITER) || die "pipe failed: $!"; $pid = fork(); - defined $pid or die "fork failed; $!"; + defined($pid) || die "first fork failed: $!"; if ($pid) { - close READER; + close READER; if (my $sub_pid = fork()) { - close WRITER; + defined($sub_pid) || die "first fork failed: $!"; + close(WRITER) || die "can't close WRITER: $!"; } else { # write to WRITER... - exit; + # ... + # then when finished + close(WRITER) || die "can't close WRITER: $!"; + exit(0); } # write to WRITER... } else { - open STDIN, "<&READER"; - close WRITER; + open(STDIN, "<&READER") || die "can't reopen STDIN: $!"; + close(WRITER) || die "can't close WRITER: $!"; # do something... - exit; + exit(0); } -Since Perl 5.8.0, you can also use the list form of C<open> for pipes : -the syntax +Since Perl 5.8.0, you can also use the list form of C<open> for pipes. +This is preferred when you wish to avoid having the shell interpret +metacharacters that may be in your command string. - open KID_PS, "-|", "ps", "aux" or die $!; +So for example, instead of using: -forks the ps(1) command (without spawning a shell, as there are more than -three arguments to open()), and reads its standard output via the -C<KID_PS> filehandle. The corresponding syntax to write to command -pipes (with C<"|-"> in place of C<"-|">) is also implemented. + open(PS_PIPE, "ps aux|") || die "can't open ps pipe: $!"; -Note that these operations are full Unix forks, which means they may not be -correctly implemented on alien systems. Additionally, these are not true -multithreading. If you'd like to learn more about threading, see the -F<modules> file mentioned below in the SEE ALSO section. +One would use either of these: -=head2 Avoiding Pipe Deadlocks + open(PS_PIPE, "-|", "ps", "aux") + || die "can't open ps pipe: $!"; -In general, if you have more than one sub-process, you need to be very -careful that any process which does not need the writer half of any -pipe you create for inter-process communication does not have it open. + @ps_args = qw[ ps aux ]; + open(PS_PIPE, "-|", @ps_args) + || die "can't open @ps_args|: $!"; -The reason for this is that any child process which is reading from -the pipe and expecting an EOF will never receive it, and therefore -never exit. A single process closing a pipe is not enough to close it; -the last process with the pipe open must close it for it to read EOF. +Because there are more than three arguments to open(), forks the ps(1) +command I<without> spawning a shell, and reads its standard output via the +C<PS_PIPE> filehandle. The corresponding syntax to I<write> to command +pipes is to use C<"|-"> in place of C<"-|">. -Certain built-in Unix features help prevent this most of -the time. For instance, filehandles have a 'close on exec' flag (set -I<en masse> with Perl using the C<$^F> L<perlvar>), so that any -filehandles which you didn't explicitly route to the STDIN, STDOUT or -STDERR of a child I<program> will automatically be closed for you. +This was admittedly a rather silly example, because you're using string +literals whose content is perfectly safe. There is therefore no cause to +resort to the harder-to-read, multi-argument form of pipe open(). However, +whenever you cannot be assured that the program arguments are free of shell +metacharacters, the fancier form of open() should be used. For example: -So, always explicitly and immediately call close() on the writable end -of any pipe, unless that process is actually writing to it. If you -don't explicitly call close() then be warned Perl will still close() -all the filehandles during global destruction. As warned above, if -those filehandles were opened with Safe Pipe Open, they will also call -waitpid() and you might again deadlock. + @grep_args = ("egrep", "-i", $some_pattern, @many_files); + open(GREP_PIPE, "-|", @grep_args) + || die "can't open @grep_args|: $!"; + +Here the multi-argument form of pipe open() is preferred because the +pattern and indeed even the filenames themselves might hold metacharacters. + +Be aware that these operations are full Unix forks, which means they may +not be correctly implemented on all alien systems. Additionally, these are +not true multithreading. To learn more about threading, see the F<modules> +file mentioned below in the SEE ALSO section. + +=head2 Avoiding Pipe Deadlocks + +Whenever you have more than one subprocess, you must be careful that each +closes whichever half of any pipes created for interprocess communication +it is not using. This is because any child process reading from the pipe +and expecting an EOF will never receive it, and therefore never exit. A +single process closing a pipe is not enough to close it; the last process +with the pipe open must close it for it to read EOF. + +Certain built-in Unix features help prevent this most of the time. For +instance, filehandles have a "close on exec" flag, which is set I<en masse> +under control of the C<$^F> variable. This is so any filehandles you +didn't explicitly route to the STDIN, STDOUT or STDERR of a child +I<program> will be automatically closed. + +Always explicitly and immediately call close() on the writable end of any +pipe, unless that process is actually writing to it. Even if you don't +explicitly call close(), Perl will still close() all filehandles during +global destruction. As previously discussed, if those filehandles have +been opened with Safe Pipe Open, this will result in calling waitpid(), +which may again deadlock. =head2 Bidirectional Communication with Another Process While this works reasonably well for unidirectional communication, what -about bidirectional communication? The obvious thing you'd like to do -doesn't actually work: +about bidirectional communication? The most obvious approach doesn't work: + # THIS DOES NOT WORK!! open(PROG_FOR_READING_AND_WRITING, "| some program |") -and if you forget to use the C<use warnings> pragma or the B<-w> flag, -then you'll miss out entirely on the diagnostic message: +If you forget to C<use warnings>, you'll miss out entirely on the +helpful diagnostic message: Can't do bidirectional pipe at -e line 1. -If you really want to, you can use the standard open2() library function -to catch both ends. There's also an open3() for tridirectional I/O so you -can also catch your child's STDERR, but doing so would then require an -awkward select() loop and wouldn't allow you to use normal Perl input -operations. +If you really want to, you can use the standard open2() from the +C<IPC::Open2> module to catch both ends. There's also an open3() in +C<IPC::Open3> for tridirectional I/O so you can also catch your child's +STDERR, but doing so would then require an awkward select() loop and +wouldn't allow you to use normal Perl input operations. If you look at its source, you'll see that open2() uses low-level -primitives like Unix pipe() and exec() calls to create all the connections. -While it might have been slightly more efficient by using socketpair(), it -would have then been even less portable than it already is. The open2() -and open3() functions are unlikely to work anywhere except on a Unix -system or some other one purporting to be POSIX compliant. +primitives like the pipe() and exec() syscalls to create all the +connections. Although it might have been more efficient by using +socketpair(), this would have been even less portable than it already +is. The open2() and open3() functions are unlikely to work anywhere +except on a Unix system, or at least one purporting POSIX compliance. + +=for TODO +Hold on, is this even true? First it says that socketpair() is avoided +for portability, but then it says it probably won't work except on +Unixy systems anyway. Which one of those is true? Here's an example of using open2(): use FileHandle; use IPC::Open2; - $pid = open2(*Reader, *Writer, "cat -u -n" ); + $pid = open2(*Reader, *Writer, "cat -un"); print Writer "stuff\n"; $got = <Reader>; -The problem with this is that Unix buffering is really going to -ruin your day. Even though your C<Writer> filehandle is auto-flushed, -and the process on the other end will get your data in a timely manner, -you can't usually do anything to force it to give it back to you -in a similarly quick fashion. In this case, we could, because we -gave I<cat> a B<-u> flag to make it unbuffered. But very few Unix -commands are designed to operate over pipes, so this seldom works -unless you yourself wrote the program on the other end of the -double-ended pipe. - -A solution to this is the nonstandard F<Comm.pl> library. It uses -pseudo-ttys to make your program behave more reasonably: - - require 'Comm.pl'; - $ph = open_proc('cat -n'); - for (1..10) { - print $ph "a line\n"; - print "got back ", scalar <$ph>; - } - -This way you don't have to have control over the source code of the -program you're using. The F<Comm> library also has expect() -and interact() functions. Find the library (and we hope its -successor F<IPC::Chat>) at your nearest CPAN archive as detailed -in the SEE ALSO section below. - -The newer Expect.pm module from CPAN also addresses this kind of thing. -This module requires two other modules from CPAN: IO::Pty and IO::Stty. -It sets up a pseudo-terminal to interact with programs that insist on -using talking to the terminal device driver. If your system is -amongst those supported, this may be your best bet. +The problem with this is that buffering is really going to ruin your +day. Even though your C<Writer> filehandle is auto-flushed so the process +on the other end gets your data in a timely manner, you can't usually do +anything to force that process to give its data to you in a similarly quick +fashion. In this special case, we could actually so, because we gave +I<cat> a B<-u> flag to make it unbuffered. But very few commands are +designed to operate over pipes, so this seldom works unless you yourself +wrote the program on the other end of the double-ended pipe. + +A solution to this is to use a library which uses pseudottys to make your +program behave more reasonably. This way you don't have to have control +over the source code of the program you're using. The C<Expect> module +from CPAN also addresses this kind of thing. This module requires two +other modules from CPAN, C<IO::Pty> and C<IO::Stty>. It sets up a pseudo +terminal to interact with programs that insist on talking to the terminal +device driver. If your system is supported, this may be your best bet. =head2 Bidirectional Communication with Yourself -If you want, you may make low-level pipe() and fork() -to stitch this together by hand. This example only -talks to itself, but you could reopen the appropriate -handles to STDIN and STDOUT and call other processes. +If you want, you may make low-level pipe() and fork() syscalls to stitch +this together by hand. This example only talks to itself, but you could +reopen the appropriate handles to STDIN and STDOUT and call other processes. +(The following example lacks proper error checking.) #!/usr/bin/perl -w # pipe1 - bidirectional communication using two pipe pairs # designed for the socketpair-challenged - use IO::Handle; # thousands of lines just for autoflush :-( - pipe(PARENT_RDR, CHILD_WTR); # XXX: failure? - pipe(CHILD_RDR, PARENT_WTR); # XXX: failure? + use IO::Handle; # thousands of lines just for autoflush :-( + pipe(PARENT_RDR, CHILD_WTR); # XXX: check failure? + pipe(CHILD_RDR, PARENT_WTR); # XXX: check failure? CHILD_WTR->autoflush(1); PARENT_WTR->autoflush(1); - if ($pid = fork) { - close PARENT_RDR; close PARENT_WTR; - print CHILD_WTR "Parent Pid $$ is sending this\n"; - chomp($line = <CHILD_RDR>); - print "Parent Pid $$ just read this: `$line'\n"; - close CHILD_RDR; close CHILD_WTR; - waitpid($pid,0); + if ($pid = fork()) { + close PARENT_RDR; + close PARENT_WTR; + print CHILD_WTR "Parent Pid $$ is sending this\n"; + chomp($line = <CHILD_RDR>); + print "Parent Pid $$ just read this: `$line'\n"; + close CHILD_RDR; close CHILD_WTR; + waitpid($pid, 0); } else { - die "cannot fork: $!" unless defined $pid; - close CHILD_RDR; close CHILD_WTR; - chomp($line = <PARENT_RDR>); - print "Child Pid $$ just read this: `$line'\n"; - print PARENT_WTR "Child Pid $$ is sending this\n"; - close PARENT_RDR; close PARENT_WTR; - exit; + die "cannot fork: $!" unless defined $pid; + close CHILD_RDR; + close CHILD_WTR; + chomp($line = <PARENT_RDR>); + print "Child Pid $$ just read this: `$line'\n"; + print PARENT_WTR "Child Pid $$ is sending this\n"; + close PARENT_RDR; + close PARENT_WTR; + exit(0); } But you don't actually have to make two pipe calls. If you @@ -874,54 +908,55 @@ have the socketpair() system call, it will do this all for you. # "the best ones always go both ways" use Socket; - use IO::Handle; # thousands of lines just for autoflush :-( + use IO::Handle; # thousands of lines just for autoflush :-( + # We say AF_UNIX because although *_LOCAL is the # POSIX 1003.1g form of the constant, many machines # still don't have it. socketpair(CHILD, PARENT, AF_UNIX, SOCK_STREAM, PF_UNSPEC) - or die "socketpair: $!"; + || die "socketpair: $!"; CHILD->autoflush(1); PARENT->autoflush(1); - if ($pid = fork) { - close PARENT; - print CHILD "Parent Pid $$ is sending this\n"; - chomp($line = <CHILD>); - print "Parent Pid $$ just read this: `$line'\n"; - close CHILD; - waitpid($pid,0); + if ($pid = fork()) { + close PARENT; + print CHILD "Parent Pid $$ is sending this\n"; + chomp($line = <CHILD>); + print "Parent Pid $$ just read this: `$line'\n"; + close CHILD; + waitpid($pid, 0); } else { - die "cannot fork: $!" unless defined $pid; - close CHILD; - chomp($line = <PARENT>); - print "Child Pid $$ just read this: `$line'\n"; - print PARENT "Child Pid $$ is sending this\n"; - close PARENT; - exit; + die "cannot fork: $!" unless defined $pid; + close CHILD; + chomp($line = <PARENT>); + print "Child Pid $$ just read this: '$line'\n"; + print PARENT "Child Pid $$ is sending this\n"; + close PARENT; + exit(0); } =head1 Sockets: Client/Server Communication -While not limited to Unix-derived operating systems (e.g., WinSock on PCs -provides socket support, as do some VMS libraries), you may not have -sockets on your system, in which case this section probably isn't going to do -you much good. With sockets, you can do both virtual circuits (i.e., TCP -streams) and datagrams (i.e., UDP packets). You may be able to do even more +While not entirely limited to Unix-derived operating systems (e.g., WinSock +on PCs provides socket support, as do some VMS libraries), you might not have +sockets on your system, in which case this section probably isn't going to +do you much good. With sockets, you can do both virtual circuits like TCP +streams and datagrams like UDP packets. You may be able to do even more depending on your system. -The Perl function calls for dealing with sockets have the same names as +The Perl functions for dealing with sockets have the same names as the corresponding system calls in C, but their arguments tend to differ -for two reasons: first, Perl filehandles work differently than C file +for two reasons. First, Perl filehandles work differently than C file descriptors. Second, Perl already knows the length of its strings, so you don't need to pass that information. -One of the major problems with old socket code in Perl was that it used -hard-coded values for some of the constants, which severely hurt -portability. If you ever see code that does anything like explicitly -setting C<$AF_INET = 2>, you know you're in for big trouble: An -immeasurably superior approach is to use the C<Socket> module, which more -reliably grants access to various constants and functions you'll need. +One of the major problems with ancient, antemillennial socket code in Perl +was that it used hard-coded values for some of the constants, which +severely hurt portability. If you ever see code that does anything like +explicitly setting C<$AF_INET = 2>, you know you're in for big trouble. +An immeasurably superior approach is to use the C<Socket> module, which more +reliably grants access to the various constants and functions you'll need. If you're not writing a server/client for an existing protocol like NNTP or SMTP, you should give some thought to how your server will @@ -938,9 +973,10 @@ Unix, that could usually be written as "\r\n", but under other systems, "\r\n" might at times be "\015\015\012", "\012\012\015", or something completely different. The standards specify writing "\015\012" to be conformant (be strict in what you provide), but they also recommend -accepting a lone "\012" on input (but be lenient in what you require). +accepting a lone "\012" on input (be lenient in what you require). We haven't always been very good about that in the code in this manpage, -but unless you're on a Mac, you'll probably be ok. +but unless you're on a Mac from way back in its pre-Unix dark ages, you'll +probably be ok. =head2 Internet TCP Clients and Servers @@ -952,51 +988,50 @@ Here's a sample TCP client using Internet-domain sockets: #!/usr/bin/perl -w use strict; use Socket; - my ($remote,$port, $iaddr, $paddr, $proto, $line); + my ($remote, $port, $iaddr, $paddr, $proto, $line); - $remote = shift || 'localhost'; + $remote = shift || "localhost"; $port = shift || 2345; # random port - if ($port =~ /\D/) { $port = getservbyname($port, 'tcp') } + if ($port =~ /\D/) { $port = getservbyname($port, "tcp") } die "No port" unless $port; - $iaddr = inet_aton($remote) || die "no host: $remote"; + $iaddr = inet_aton($remote) || die "no host: $remote"; $paddr = sockaddr_in($port, $iaddr); - $proto = getprotobyname('tcp'); - socket(SOCK, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; - connect(SOCK, $paddr) || die "connect: $!"; - while (defined($line = <SOCK>)) { - print $line; + $proto = getprotobyname("tcp"); + socket(SOCK, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; + connect(SOCK, $paddr) || die "connect: $!"; + while ($line = <SOCK>) { + print $line; } - close (SOCK) || die "close: $!"; - exit; + close (SOCK) || die "close: $!"; + exit(0); And here's a corresponding server to go along with it. We'll -leave the address as INADDR_ANY so that the kernel can choose +leave the address as C<INADDR_ANY> so that the kernel can choose the appropriate interface on multihomed hosts. If you want sit on a particular interface (like the external side of a gateway -or firewall machine), you should fill this in with your real address -instead. +or firewall machine), fill this in with your real address instead. #!/usr/bin/perl -Tw use strict; - BEGIN { $ENV{PATH} = '/usr/ucb:/bin' } + BEGIN { $ENV{PATH} = "/usr/bin:/bin" } use Socket; use Carp; my $EOL = "\015\012"; - sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } + sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" } - my $port = shift || 2345; - my $proto = getprotobyname('tcp'); + my $port = shift || 2345; + die "invalid port" unless if $port =~ /^ \d+ $/x; - ($port) = $port =~ /^(\d+)$/ or die "invalid port"; + my $proto = getprotobyname("tcp"); - socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; - setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, - pack("l", 1)) || die "setsockopt: $!"; - bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!"; - listen(Server,SOMAXCONN) || die "listen: $!"; + socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; + setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1)) + || die "setsockopt: $!"; + bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!"; + listen(Server, SOMAXCONN) || die "listen: $!"; logmsg "server started on port $port"; @@ -1004,43 +1039,43 @@ instead. $SIG{CHLD} = \&REAPER; - for ( ; $paddr = accept(Client,Server); close Client) { - my($port,$iaddr) = sockaddr_in($paddr); - my $name = gethostbyaddr($iaddr,AF_INET); + for ( ; $paddr = accept(Client, Server); close Client) { + my($port, $iaddr) = sockaddr_in($paddr); + my $name = gethostbyaddr($iaddr, AF_INET); - logmsg "connection from $name [", - inet_ntoa($iaddr), "] - at port $port"; + logmsg "connection from $name [", + inet_ntoa($iaddr), "] + at port $port"; - print Client "Hello there, $name, it's now ", - scalar localtime, $EOL; + print Client "Hello there, $name, it's now ", + scalar localtime(), $EOL; } And here's a multithreaded version. It's multithreaded in that -like most typical servers, it spawns (forks) a slave server to +like most typical servers, it spawns (fork()s) a slave server to handle the client request so that the master server can quickly go back to service a new client. #!/usr/bin/perl -Tw use strict; - BEGIN { $ENV{PATH} = '/usr/ucb:/bin' } + BEGIN { $ENV{PATH} = "/usr/bin:/bin" } use Socket; use Carp; my $EOL = "\015\012"; sub spawn; # forward declaration - sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } + sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" } - my $port = shift || 2345; - my $proto = getprotobyname('tcp'); + my $port = shift || 2345; + die "invalid port" unless if $port =~ /^ \d+ $/x; - ($port) = $port =~ /^(\d+)$/ or die "invalid port"; + my $proto = getprotobyname("tcp"); - socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; - setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, - pack("l", 1)) || die "setsockopt: $!"; - bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!"; - listen(Server,SOMAXCONN) || die "listen: $!"; + socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; + setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1)) + || die "setsockopt: $!"; + bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!"; + listen(Server, SOMAXCONN) || die "listen: $!"; logmsg "server started on port $port"; @@ -1052,17 +1087,17 @@ go back to service a new client. sub REAPER { local $!; # don't let waitpid() overwrite current error - while ((my $pid = waitpid(-1,WNOHANG)) > 0 && WIFEXITED($?)) { - logmsg "reaped $waitedpid" . ($? ? " with exit $?" : ''); + while ((my $pid = waitpid(-1, WNOHANG)) > 0 && WIFEXITED($?)) { + logmsg "reaped $waitedpid" . ($? ? " with exit $?" : ""); } $SIG{CHLD} = \&REAPER; # loathe SysV } $SIG{CHLD} = \&REAPER; - while(1) { + while (1) { $paddr = accept(Client, Server) || do { - # try again if accept() returned because a signal was received + # try again if accept() returned because got a signal next if $!{EINTR}; die "accept: $!"; }; @@ -1074,9 +1109,9 @@ go back to service a new client. "] at port $port"; spawn sub { - $|=1; - print "Hello there, $name, it's now ", scalar localtime, $EOL; - exec '/usr/games/fortune' # XXX: `wrong' line terminators + $| = 1; + print "Hello there, $name, it's now ", scalar localtime(), $EOL; + exec "/usr/games/fortune" # XXX: "wrong" line terminators or confess "can't exec fortune: $!"; }; close Client; @@ -1085,12 +1120,12 @@ go back to service a new client. sub spawn { my $coderef = shift; - unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') { + unless (@_ == 0 && $coderef && ref($coderef) eq "CODE") { confess "usage: spawn CODEREF"; } my $pid; - if (! defined($pid = fork)) { + unless (defined($pid = fork())) { logmsg "cannot fork: $!"; return; } @@ -1100,10 +1135,10 @@ go back to service a new client. } # else I'm the child -- go spawn - open(STDIN, "<&Client") || die "can't dup client to stdin"; - open(STDOUT, ">&Client") || die "can't dup client to stdout"; + open(STDIN, "<&Client") || die "can't dup client to stdin"; + open(STDOUT, ">&Client") || die "can't dup client to stdout"; ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr"; - exit &$coderef(); + exit($coderef->()); } This server takes the trouble to clone off a child version via fork() @@ -1118,25 +1153,25 @@ ensuring that they terminate cleanly and don't join the ranks of the living dead. Within the while loop we call accept() and check to see if it returns -a false value. This would normally indicate a system error that needs -to be reported. However the introduction of safe signals (see +a false value. This would normally indicate a system error needs +to be reported. However, the introduction of safe signals (see L</Deferred Signals (Safe Signals)> above) in Perl 5.7.3 means that -accept() may also be interrupted when the process receives a signal. -This typically happens when one of the forked sub-processes exits and +accept() might also be interrupted when the process receives a signal. +This typically happens when one of the forked subprocesses exits and notifies the parent process with a CHLD signal. -If accept() is interrupted by a signal then $! will be set to EINTR. -If this happens then we can safely continue to the next iteration of +If accept() is interrupted by a signal, $! will be set to EINTR. +If this happens, we can safely continue to the next iteration of the loop and another call to accept(). It is important that your -signal handling code doesn't modify the value of $! or this test will -most likely fail. In the REAPER subroutine we create a local version -of $! before calling waitpid(). When waitpid() sets $! to ECHILD (as -it inevitably does when it has no more children waiting), it will -update the local copy leaving the original unchanged. +signal handling code not modify the value of $!, or else this test +will likely fail. In the REAPER subroutine we create a local version +of $! before calling waitpid(). When waitpid() sets $! to ECHILD as +it inevitably does when it has no more children waiting, it +updates the local copy and leaves the original unchanged. -We suggest that you use the B<-T> flag to use taint checking (see L<perlsec>) +You should use the B<-T> flag to enable taint checking (see L<perlsec>) even if we aren't running setuid or setgid. This is always a good idea -for servers and other programs run on behalf of someone else (like CGI +for servers or any program run on behalf of someone else (like CGI scripts), because it lessens the chances that people from the outside will be able to compromise your system. @@ -1148,29 +1183,30 @@ differ from the system on which it's being run: use strict; use Socket; - my $SECS_of_70_YEARS = 2208988800; - sub ctime { scalar localtime(shift) } + my $SECS_OF_70_YEARS = 2208988800; + sub ctime { scalar localtime(shift() || time()) } - my $iaddr = gethostbyname('localhost'); - my $proto = getprotobyname('tcp'); - my $port = getservbyname('time', 'tcp'); + my $iaddr = gethostbyname("localhost"); + my $proto = getprotobyname("tcp"); + my $port = getservbyname("time", "tcp"); my $paddr = sockaddr_in(0, $iaddr); my($host); $| = 1; - printf "%-24s %8s %s\n", "localhost", 0, ctime(time()); + printf "%-24s %8s %s\n", "localhost", 0, ctime(); foreach $host (@ARGV) { - printf "%-24s ", $host; - my $hisiaddr = inet_aton($host) || die "unknown host"; - my $hispaddr = sockaddr_in($port, $hisiaddr); - socket(SOCKET, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; - connect(SOCKET, $hispaddr) || die "connect: $!"; - my $rtime = ' '; - read(SOCKET, $rtime, 4); - close(SOCKET); - my $histime = unpack("N", $rtime) - $SECS_of_70_YEARS; - printf "%8d %s\n", $histime - time, ctime($histime); + printf "%-24s ", $host; + my $hisiaddr = inet_aton($host) || die "unknown host"; + my $hispaddr = sockaddr_in($port, $hisiaddr); + socket(SOCKET, PF_INET, SOCK_STREAM, $proto) + || die "socket: $!"; + connect(SOCKET, $hispaddr) || die "connect: $!"; + my $rtime = pack("C4", ()); + read(SOCKET, $rtime, 4); + close(SOCKET); + my $histime = unpack("N", $rtime) - $SECS_OF_70_YEARS; + printf "%8d %s\n", $histime - time(), ctime($histime); } =head2 Unix-Domain TCP Clients and Servers @@ -1186,8 +1222,8 @@ domain sockets can show up in the file system with an ls(1) listing. You can test for these with Perl's B<-S> file test: - unless ( -S '/dev/log' ) { - die "something's wicked with the log system"; + unless (-S "/dev/log") { + die "something's wicked with the log system"; } Here's a sample Unix-domain client: @@ -1197,13 +1233,13 @@ Here's a sample Unix-domain client: use strict; my ($rendezvous, $line); - $rendezvous = shift || 'catsock'; - socket(SOCK, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!"; - connect(SOCK, sockaddr_un($rendezvous)) || die "connect: $!"; + $rendezvous = shift || "catsock"; + socket(SOCK, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!"; + connect(SOCK, sockaddr_un($rendezvous)) || die "connect: $!"; while (defined($line = <SOCK>)) { - print $line; + print $line; } - exit; + exit(0); And here's a corresponding server. You don't have to worry about silly network terminators here because Unix domain sockets are guaranteed @@ -1214,18 +1250,18 @@ to be on the localhost, and thus everything works right. use Socket; use Carp; - BEGIN { $ENV{PATH} = '/usr/ucb:/bin' } + BEGIN { $ENV{PATH} = "/usr/bin:/bin" } sub spawn; # forward declaration - sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } + sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" } - my $NAME = 'catsock'; + my $NAME = "catsock"; my $uaddr = sockaddr_un($NAME); - my $proto = getprotobyname('tcp'); + my $proto = getprotobyname("tcp"); - socket(Server,PF_UNIX,SOCK_STREAM,0) || die "socket: $!"; + socket(Server, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!"; unlink($NAME); - bind (Server, $uaddr) || die "bind: $!"; - listen(Server,SOMAXCONN) || die "listen: $!"; + bind (Server, $uaddr) || die "bind: $!"; + listen(Server, SOMAXCONN) || die "listen: $!"; logmsg "server started on $NAME"; @@ -1233,64 +1269,66 @@ to be on the localhost, and thus everything works right. use POSIX ":sys_wait_h"; sub REAPER { - my $child; - while (($waitedpid = waitpid(-1,WNOHANG)) > 0) { - logmsg "reaped $waitedpid" . ($? ? " with exit $?" : ''); - } - $SIG{CHLD} = \&REAPER; # loathe SysV + my $child; + while (($waitedpid = waitpid(-1, WNOHANG)) > 0) { + logmsg "reaped $waitedpid" . ($? ? " with exit $?" : ""); + } + $SIG{CHLD} = \&REAPER; # loathe SysV } $SIG{CHLD} = \&REAPER; for ( $waitedpid = 0; - accept(Client,Server) || $waitedpid; - $waitedpid = 0, close Client) + accept(Client, Server) || $waitedpid; + $waitedpid = 0, close Client) { - next if $waitedpid; - logmsg "connection on $NAME"; - spawn sub { - print "Hello there, it's now ", scalar localtime, "\n"; - exec '/usr/games/fortune' or die "can't exec fortune: $!"; - }; + next if $waitedpid; + logmsg "connection on $NAME"; + spawn sub { + print "Hello there, it's now ", scalar localtime(), "\n"; + exec("/usr/games/fortune") || die "can't exec fortune: $!"; + }; } sub spawn { - my $coderef = shift; - - unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') { - confess "usage: spawn CODEREF"; - } - - my $pid; - if (!defined($pid = fork)) { - logmsg "cannot fork: $!"; - return; - } elsif ($pid) { - logmsg "begat $pid"; - return; # I'm the parent - } - # else I'm the child -- go spawn - - open(STDIN, "<&Client") || die "can't dup client to stdin"; - open(STDOUT, ">&Client") || die "can't dup client to stdout"; - ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr"; - exit &$coderef(); + my $coderef = shift(); + + unless (@_ == 0 && $coderef && ref($coderef) eq "CODE") { + confess "usage: spawn CODEREF"; + } + + my $pid; + unless (defined($pid = fork())) { + logmsg "cannot fork: $!"; + return; + } + elsif ($pid) { + logmsg "begat $pid"; + return; # I'm the parent + } + else { + # I'm the child -- go spawn + } + + open(STDIN, "<&Client") || die "can't dup client to stdin"; + open(STDOUT, ">&Client") || die "can't dup client to stdout"; + ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr"; + exit($coderef->()); } As you see, it's remarkably similar to the Internet domain TCP server, so much so, in fact, that we've omitted several duplicate functions--spawn(), -logmsg(), ctime(), and REAPER()--which are exactly the same as in the -other server. +logmsg(), ctime(), and REAPER()--which are the same as in the other server. So why would you ever want to use a Unix domain socket instead of a simpler named pipe? Because a named pipe doesn't give you sessions. You can't tell one process's data from another's. With socket programming, -you get a separate session for each client: that's why accept() takes two +you get a separate session for each client; that's why accept() takes two arguments. -For example, let's say that you have a long running database server daemon -that you want folks from the World Wide Web to be able to access, but only +For example, let's say that you have a long-running database server daemon +that you want folks to be able to access from the Web, but only if they go through a CGI interface. You'd have a small, simple CGI program that does whatever checks and logging you feel like, and then acts as a Unix-domain client and connects to your private server. @@ -1298,13 +1336,13 @@ as a Unix-domain client and connects to your private server. =head1 TCP Clients with IO::Socket For those preferring a higher-level interface to socket programming, the -IO::Socket module provides an object-oriented approach. IO::Socket is -included as part of the standard Perl distribution as of the 5.004 -release. If you're running an earlier version of Perl, just fetch -IO::Socket from CPAN, where you'll also find modules providing easy -interfaces to the following systems: DNS, FTP, Ident (RFC 931), NIS and -NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay, Telnet, and Time--just -to name a few. +IO::Socket module provides an object-oriented approach. IO::Socket has +been included in the standard Perl distribution ever since Perl 5.004. If +you're running an earlier version of Perl (in which case, how are you +reading this manpage?), just fetch IO::Socket from CPAN, where you'll also +find modules providing easy interfaces to the following systems: DNS, FTP, +Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay, +Telnet, and Time--to name just a few. =head2 A Simple Client @@ -1315,19 +1353,19 @@ that the server there cares to provide. #!/usr/bin/perl -w use IO::Socket; $remote = IO::Socket::INET->new( - Proto => "tcp", - PeerAddr => "localhost", - PeerPort => "daytime(13)", - ) - or die "cannot connect to daytime port at localhost"; - while ( <$remote> ) { print } + Proto => "tcp", + PeerAddr => "localhost", + PeerPort => "daytime(13)", + ) + || die "can't connect to daytime service on localhost"; + while (<$remote>) { print } When you run this program, you should get something back that looks like this: Wed May 14 08:40:46 MDT 1997 -Here are what those parameters to the C<new> constructor mean: +Here are what those parameters to the new() constructor mean: =over 4 @@ -1343,25 +1381,25 @@ can be used to make a datagram socket, used for message-passing. This is the name or Internet address of the remote host the server is running on. We could have specified a longer name like C<"www.perl.com">, -or an address like C<"204.148.40.9">. For demonstration purposes, we've +or an address like C<"207.171.7.72">. For demonstration purposes, we've used the special hostname C<"localhost">, which should always mean the current machine you're running on. The corresponding Internet address -for localhost is C<"127.1">, if you'd rather use that. +for localhost is C<"127.0.0.1">, if you'd rather use that. =item C<PeerPort> This is the service name or port number we'd like to connect to. We could have gotten away with using just C<"daytime"> on systems with a well-configured system services file,[FOOTNOTE: The system services file -is in I</etc/services> under Unix] but just in case, we've specified the -port number (13) in parentheses. Using just the number would also have -worked, but constant numbers make careful programmers nervous. +is found in I</etc/services> under Unixy systems.] but here we've specified the +port number (13) in parentheses. Using just the number would have also +worked, but numeric literals make careful programmers nervous. =back Notice how the return value from the C<new> constructor is used as -a filehandle in the C<while> loop? That's what's called an indirect -filehandle, a scalar variable containing a filehandle. You can use +a filehandle in the C<while> loop? That's what's called an I<indirect +filehandle>, a scalar variable containing a filehandle. You can use it the same way you would a normal filehandle. For example, you can read one line from it this way: @@ -1378,36 +1416,35 @@ and send a line of data to it this way: =head2 A Webget Client Here's a simple client that takes a remote host to fetch a document -from, and then a list of documents to get from that host. This is a +from, and then a list of files to get from that host. This is a more interesting client than the previous one because it first sends something to the server before fetching the server's response. #!/usr/bin/perl -w use IO::Socket; - unless (@ARGV > 1) { die "usage: $0 host document ..." } + unless (@ARGV > 1) { die "usage: $0 host url ..." } $host = shift(@ARGV); $EOL = "\015\012"; $BLANK = $EOL x 2; - foreach $document ( @ARGV ) { - $remote = IO::Socket::INET->new( Proto => "tcp", - PeerAddr => $host, - PeerPort => "http(80)", - ); - unless ($remote) { die "cannot connect to http daemon on $host" } - $remote->autoflush(1); - print $remote "GET $document HTTP/1.0" . $BLANK; - while ( <$remote> ) { print } - close $remote; + for my $document (@ARGV) { + $remote = IO::Socket::INET->new( Proto => "tcp", + PeerAddr => $host, + PeerPort => "http(80)", + ) || die "cannot connect to httpd on $host"; + $remote->autoflush(1); + print $remote "GET $document HTTP/1.0" . $BLANK; + while ( <$remote> ) { print } + close $remote; } -The web server handing the "http" service, which is assumed to be at -its standard port, number 80. If the web server you're trying to -connect to is at a different port (like 1080 or 8080), you should specify +The web server handling the HTTP service is assumed to be at +its standard port, number 80. If the server you're trying to +connect to is at a different port, like 1080 or 8080, you should specify it as the named-parameter pair, C<< PeerPort => 8080 >>. The C<autoflush> method is used on the socket because otherwise the system would buffer -up the output we sent it. (If you're on a Mac, you'll also need to -change every C<"\n"> in your code that sends data over the network to -be a C<"\015\012"> instead.) +up the output we sent it. (If you're on a prehistoric Mac, you'll also +need to change every C<"\n"> in your code that sends data over the network +to be a C<"\015\012"> instead.) Connecting to the server is only the first part of the process: once you have the connection, you have to use the server's language. Each server @@ -1437,7 +1474,7 @@ Here's an example of running that program, which we'll call I<webget>: Ok, so that's not very interesting, because it didn't find that particular document. But a long response wouldn't have fit on this page. -For a more fully-featured version of this program, you should look to +For a more featureful version of this program, you should look to the I<lwp-request> program included with the LWP modules from CPAN. =head2 Interactive Client with IO::Socket @@ -1472,11 +1509,11 @@ Here's the code: # create a tcp connection to the specified host and port $handle = IO::Socket::INET->new(Proto => "tcp", - PeerAddr => $host, - PeerPort => $port) - or die "can't connect to port $port on $host: $!"; + PeerAddr => $host, + PeerPort => $port) + || die "can't connect to port $port on $host: $!"; - $handle->autoflush(1); # so output gets there right away + $handle->autoflush(1); # so output gets there right away print STDERR "[Connected to $host:$port]\n"; # split the program into two processes, identical twins @@ -1484,22 +1521,23 @@ Here's the code: # the if{} block runs only in the parent process if ($kidpid) { - # copy the socket to standard output - while (defined ($line = <$handle>)) { - print STDOUT $line; - } - kill("TERM", $kidpid); # send SIGTERM to child + # copy the socket to standard output + while (defined ($line = <$handle>)) { + print STDOUT $line; + } + kill("TERM", $kidpid); # send SIGTERM to child } # the else{} block runs only in the child process else { - # copy standard input to the socket - while (defined ($line = <STDIN>)) { - print $handle $line; - } + # copy standard input to the socket + while (defined ($line = <STDIN>)) { + print $handle $line; + } + exit(0); # just in case } The C<kill> function in the parent's C<if> block is there to send a -signal to our child process (current running in the C<else> block) +signal to our child process, currently running in the C<else> block, as soon as the remote server has closed its end of the connection. If the remote server sends data a byte at time, and you need that @@ -1509,7 +1547,7 @@ following: my $byte; while (sysread($handle, $byte, 1) == 1) { - print STDOUT $byte; + print STDOUT $byte; } Making a system call for each byte you want to read is not very efficient @@ -1569,20 +1607,20 @@ To add to user-friendliness, our server prompts the user for commands. Most servers don't do this. Because of the prompt without a newline, you'll have to use the C<sysread> variant of the interactive client above. -This server accepts one of five different commands, sending output -back to the client. Note that unlike most network servers, this one -only handles one incoming client at a time. Multithreaded servers are -covered in Chapter 6 of the Camel. +This server accepts one of five different commands, sending output back to +the client. Unlike most network servers, this one handles only one +incoming client at a time. Multithreaded servers are covered in +Chapter 16 of the Camel. Here's the code. We'll #!/usr/bin/perl -w use IO::Socket; - use Net::hostent; # for OO version of gethostbyaddr + use Net::hostent; # for OOish version of gethostbyaddr - $PORT = 9000; # pick something not in use + $PORT = 9000; # pick something not in use - $server = IO::Socket::INET->new( Proto => 'tcp', + $server = IO::Socket::INET->new( Proto => "tcp", LocalPort => $PORT, Listen => SOMAXCONN, Reuse => 1); @@ -1597,12 +1635,12 @@ Here's the code. We'll printf "[Connect from %s]\n", $hostinfo ? $hostinfo->name : $client->peerhost; print $client "Command? "; while ( <$client>) { - next unless /\S/; # blank line - if (/quit|exit/i) { last; } - elsif (/date|time/i) { printf $client "%s\n", scalar localtime; } - elsif (/who/i ) { print $client `who 2>&1`; } - elsif (/cookie/i ) { print $client `/usr/games/fortune 2>&1`; } - elsif (/motd/i ) { print $client `cat /etc/motd 2>&1`; } + next unless /\S/; # blank line + if (/quit|exit/i) { last } + elsif (/date|time/i) { printf $client "%s\n", scalar localtime() } + elsif (/who/i ) { print $client `who 2>&1` } + elsif (/cookie/i ) { print $client `/usr/games/fortune 2>&1` } + elsif (/motd/i ) { print $client `cat /etc/motd 2>&1` } else { print $client "Commands: quit date who cookie motd\n"; } @@ -1624,10 +1662,10 @@ find yourself overly concerned about reliability and start building checks into your message system, then you probably should use just TCP to start with. -Note that UDP datagrams are I<not> a bytestream and should not be treated -as such. This makes using I/O mechanisms with internal buffering -like stdio (i.e. print() and friends) especially cumbersome. Use syswrite(), -or better send(), like in the example below. +UDP datagrams are I<not> a bytestream and should not be treated as such. +This makes using I/O mechanisms with internal buffering like stdio (i.e. +print() and friends) especially cumbersome. Use syswrite(), or better +send(), like in the example below. Here's a UDP program similar to the sample Internet TCP client given earlier. However, instead of checking one host at a time, the UDP version @@ -1641,85 +1679,87 @@ with TCP, you'd have to use a different socket handle for each host. use Sys::Hostname; my ( $count, $hisiaddr, $hispaddr, $histime, - $host, $iaddr, $paddr, $port, $proto, - $rin, $rout, $rtime, $SECS_of_70_YEARS); + $host, $iaddr, $paddr, $port, $proto, + $rin, $rout, $rtime, $SECS_OF_70_YEARS); - $SECS_of_70_YEARS = 2208988800; + $SECS_OF_70_YEARS = 2_208_988_800; $iaddr = gethostbyname(hostname()); - $proto = getprotobyname('udp'); - $port = getservbyname('time', 'udp'); + $proto = getprotobyname("udp"); + $port = getservbyname("time", "udp"); $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick socket(SOCKET, PF_INET, SOCK_DGRAM, $proto) || die "socket: $!"; bind(SOCKET, $paddr) || die "bind: $!"; $| = 1; - printf "%-12s %8s %s\n", "localhost", 0, scalar localtime time; + printf "%-12s %8s %s\n", "localhost", 0, scalar localtime(); $count = 0; for $host (@ARGV) { - $count++; - $hisiaddr = inet_aton($host) || die "unknown host"; - $hispaddr = sockaddr_in($port, $hisiaddr); - defined(send(SOCKET, 0, 0, $hispaddr)) || die "send $host: $!"; + $count++; + $hisiaddr = inet_aton($host) || die "unknown host"; + $hispaddr = sockaddr_in($port, $hisiaddr); + defined(send(SOCKET, 0, 0, $hispaddr)) || die "send $host: $!"; } - $rin = ''; + $rin = ""; vec($rin, fileno(SOCKET), 1) = 1; # timeout after 10.0 seconds while ($count && select($rout = $rin, undef, undef, 10.0)) { - $rtime = ''; - ($hispaddr = recv(SOCKET, $rtime, 4, 0)) || die "recv: $!"; - ($port, $hisiaddr) = sockaddr_in($hispaddr); - $host = gethostbyaddr($hisiaddr, AF_INET); - $histime = unpack("N", $rtime) - $SECS_of_70_YEARS; - printf "%-12s ", $host; - printf "%8d %s\n", $histime - time, scalar localtime($histime); - $count--; + $rtime = ""; + $hispaddr = recv(SOCKET, $rtime, 4, 0) || die "recv: $!"; + ($port, $hisiaddr) = sockaddr_in($hispaddr); + $host = gethostbyaddr($hisiaddr, AF_INET); + $histime = unpack("N", $rtime) - $SECS_OF_70_YEARS; + printf "%-12s ", $host; + printf "%8d %s\n", $histime - time(), scalar localtime($histime); + $count--; } -Note that this example does not include any retries and may consequently -fail to contact a reachable host. The most prominent reason for this -is congestion of the queues on the sending host if the number of -list of hosts to contact is sufficiently large. +This example does not include any retries and may consequently fail to +contact a reachable host. The most prominent reason for this is congestion +of the queues on the sending host if the number of hosts to contact is +sufficiently large. =head1 SysV IPC While System V IPC isn't so widely used as sockets, it still has some -interesting uses. You can't, however, effectively use SysV IPC or -Berkeley mmap() to have shared memory so as to share a variable amongst -several processes. That's because Perl would reallocate your string when -you weren't wanting it to. +interesting uses. However, you cannot use SysV IPC or Berkeley mmap() to +have a variable shared amongst several processes. That's because Perl +would reallocate your string when you weren't wanting it to. You might +look into the C<IPC::Shareable> or C<threads::shared> modules for that. Here's a small example showing shared memory usage. use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRUSR S_IWUSR); $size = 2000; - $id = shmget(IPC_PRIVATE, $size, S_IRUSR|S_IWUSR) // die "$!"; + $id = shmget(IPC_PRIVATE, $size, S_IRUSR | S_IWUSR); + defined($id) || die "shmget: $!"; print "shm key $id\n"; $message = "Message #1"; - shmwrite($id, $message, 0, 60) || die "$!"; + shmwrite($id, $message, 0, 60) || die "shmwrite: $!"; print "wrote: '$message'\n"; - shmread($id, $buff, 0, 60) || die "$!"; + shmread($id, $buff, 0, 60) || die "shmread: $!"; print "read : '$buff'\n"; # the buffer of shmread is zero-character end-padded. - substr($buff, index($buff, "\0")) = ''; + substr($buff, index($buff, "\0")) = "": print "un" unless $buff eq $message; print "swell\n"; print "deleting shm $id\n"; - shmctl($id, IPC_RMID, 0) || die "$!"; + shmctl($id, IPC_RMID, 0) || die "shmctl: $!"; Here's an example of a semaphore: use IPC::SysV qw(IPC_CREAT); $IPC_KEY = 1234; - $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) // die "$!"; + $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT); + defined($id) || die "shmget: $!"; print "shm key $id\n"; Put this code in a separate file to be run in more than one process. @@ -1728,13 +1768,13 @@ Call the file F<take>: # create a semaphore $IPC_KEY = 1234; - $id = semget($IPC_KEY, 0 , 0 ); - die if !defined($id); + $id = semget($IPC_KEY, 0, 0); + defined($id) || die "shmget: $!"; - $semnum = 0; + $semnum = 0; $semflag = 0; - # 'take' semaphore + # "take" semaphore # wait for semaphore to be zero $semop = 0; $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag); @@ -1742,29 +1782,29 @@ Call the file F<take>: # Increment the semaphore count $semop = 1; $opstring2 = pack("s!s!s!", $semnum, $semop, $semflag); - $opstring = $opstring1 . $opstring2; + $opstring = $opstring1 . $opstring2; - semop($id,$opstring) || die "$!"; + semop($id, $opstring) || die "semop: $!"; Put this code in a separate file to be run in more than one process. Call this file F<give>: - # 'give' the semaphore + # "give" the semaphore # run this in the original process and you will see # that the second process continues $IPC_KEY = 1234; $id = semget($IPC_KEY, 0, 0); - die if !defined($id); + die unless defined($id); - $semnum = 0; + $semnum = 0; $semflag = 0; # Decrement the semaphore count $semop = -1; $opstring = pack("s!s!s!", $semnum, $semop, $semflag); - semop($id,$opstring) || die "$!"; + semop($id, $opstring) || die "semop: $!"; The SysV IPC code above was written long ago, and it's definitely clunky looking. For a more modern look, see the IPC::SysV module @@ -1775,41 +1815,36 @@ A small example demonstrating SysV message queues: use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRUSR S_IWUSR); my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRUSR | S_IWUSR); + defined($id) || die "msgget failed: $!"; - my $sent = "message"; + my $sent = "message"; my $type_sent = 1234; - my $rcvd; - my $type_rcvd; - - if (defined $id) { - if (msgsnd($id, pack("l! a*", $type_sent, $sent), 0)) { - if (msgrcv($id, $rcvd, 60, 0, 0)) { - ($type_rcvd, $rcvd) = unpack("l! a*", $rcvd); - if ($rcvd eq $sent) { - print "okay\n"; - } else { - print "not okay\n"; - } - } else { - die "# msgrcv failed\n"; - } - } else { - die "# msgsnd failed\n"; - } - msgctl($id, IPC_RMID, 0) || die "# msgctl failed: $!\n"; + + msgsnd($id, pack("l! a*", $type_sent, $sent), 0) + || die "msgsnd failed: $!"; + + msgrcv($id, my $rcvd_buf, 60, 0, 0) + || die "msgrcv failed: $!"; + + my($type_rcvd, $rcvd) = unpack("l! a*", $rcvd_buf); + + if ($rcvd eq $sent) { + print "okay\n"; } else { - die "# msgget failed\n"; + print "not okay\n"; } + msgctl($id, IPC_RMID, 0) || die "msgctl failed: $!\n"; + =head1 NOTES Most of these routines quietly but politely return C<undef> when they fail instead of causing your program to die right then and there due to an uncaught exception. (Actually, some of the new I<Socket> conversion -functions croak() on bad arguments.) It is therefore essential to +functions do croak() on bad arguments.) It is therefore essential to check return values from these functions. Always begin your socket -programs this way for optimal success, and don't forget to add B<-T> -taint checking flag to the #! line for servers: +programs this way for optimal success, and don't forget to add the B<-T> +taint-checking flag to the C<#!> line for servers: #!/usr/bin/perl -Tw use strict; @@ -1818,9 +1853,9 @@ taint checking flag to the #! line for servers: =head1 BUGS -All these routines create system-specific portability problems. As noted +These routines all create system-specific portability problems. As noted elsewhere, Perl is at the mercy of your C libraries for much of its system -behaviour. It's probably safest to assume broken SysV semantics for +behavior. It's probably safest to assume broken SysV semantics for signals and to stick with simple TCP and UDP socket operations; e.g., don't try to pass open file descriptors over a local UDP datagram socket if you want your code to stand a chance of being portable. @@ -1835,20 +1870,23 @@ version and suggestions from the Perl Porters. There's a lot more to networking than this, but this should get you started. -For intrepid programmers, the indispensable textbook is I<Unix -Network Programming, 2nd Edition, Volume 1> by W. Richard Stevens -(published by Prentice-Hall). Note that most books on networking -address the subject from the perspective of a C programmer; translation -to Perl is left as an exercise for the reader. +For intrepid programmers, the indispensable textbook is I<Unix Network +Programming, 2nd Edition, Volume 1> by W. Richard Stevens (published by +Prentice-Hall). Most books on networking address the subject from the +perspective of a C programmer; translation to Perl is left as an exercise +for the reader. The IO::Socket(3) manpage describes the object library, and the Socket(3) manpage describes the low-level interface to sockets. Besides the obvious -functions in L<perlfunc>, you should also check out the F<modules> file -at your nearest CPAN site. (See L<perlmodlib> or best yet, the F<Perl -FAQ> for a description of what CPAN is and where to get it.) - -Section 5 of the F<modules> file is devoted to "Networking, Device Control -(modems), and Interprocess Communication", and contains numerous unbundled -modules numerous networking modules, Chat and Expect operations, CGI -programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet, -Threads, and ToolTalk--just to name a few. +functions in L<perlfunc>, you should also check out the F<modules> file at +your nearest CPAN site, especially +L<http://www.cpan.org/modules/00modlist.long.html#ID5_Networking_>. +See L<perlmodlib> or best yet, the F<Perl FAQ> for a description +of what CPAN is and where to get it if the previous link doesn't work +for you. + +Section 5 of CPAN's F<modules> file is devoted to "Networking, Device +Control (modems), and Interprocess Communication", and contains numerous +unbundled modules numerous networking modules, Chat and Expect operations, +CGI programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet, +Threads, and ToolTalk--to name just a few. diff --git a/Master/tlpkg/tlperl/lib/pods/perljp.pod b/Master/tlpkg/tlperl/lib/pods/perljp.pod index 6f022bbdbe1..934a91f9180 100644 --- a/Master/tlpkg/tlperl/lib/pods/perljp.pod +++ b/Master/tlpkg/tlperl/lib/pods/perljp.pod @@ -178,7 +178,7 @@ Unicode ¥³¥ó¥½¡¼¥·¥¢¥à (Unicodeµ¬³Ê¤ÎÁªÄêÃÄÂÎ) UTF-8 and Unicode FAQ for Unix/Linux -=item L<http://kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html> +=item L<http://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html> UTF-8 and Unicode FAQ for Unix/Linux (¥Ï¥ó¥°¥ëÌõ) diff --git a/Master/tlpkg/tlperl/lib/pods/perlko.pod b/Master/tlpkg/tlperl/lib/pods/perlko.pod index 611ed7c3fde..5e9c4760192 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlko.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlko.pod @@ -188,7 +188,7 @@ Character Set)À» ¸¸µå´Â ISO/IEC JTC1/SC2/WG2ÀÇ À¥ ÆäÀÌÁö. À¯´Ð½º/¸®´ª½º¿¡¼ À¯´ÏÄÚµå¿Í UTF-8 »ç¿ë¿¡ ´ëÇÑ ¹®´äÁý(FAQ) -=item L<http://kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html> +=item L<http://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html> À¯´Ð½º/¸®´ª½º¿¡¼ À¯´ÏÄÚµå¿Í UTF-8 »ç¿ë¿¡ ´ëÇÑ ¹®´äÁý(FAQ)ÀÇ Çѱ¹¾î ¹ø¿ª diff --git a/Master/tlpkg/tlperl/lib/pods/perllexwarn.pod b/Master/tlpkg/tlperl/lib/pods/perllexwarn.pod index 835914e4869..accbfdf7923 100644 --- a/Master/tlpkg/tlperl/lib/pods/perllexwarn.pod +++ b/Master/tlpkg/tlperl/lib/pods/perllexwarn.pod @@ -304,7 +304,13 @@ The current hierarchy is: | +- untie | - +- utf8 + +- utf8----------+ + | | + | +- surrogate + | | + | +- non_unicode + | | + | +- nonchar | +- void @@ -520,6 +526,16 @@ a warning. Notice also that the warning is reported at the line where the object is first used. +When registering new categories of warning, you can supply more names to +warnings::register like this: + + package MyModule; + use warnings::register qw(format precision); + + ... + + warnings::warnif('MyModule::format', '...'); + =head1 SEE ALSO L<warnings>, L<perldiag>. diff --git a/Master/tlpkg/tlperl/lib/pods/perllinux.pod b/Master/tlpkg/tlperl/lib/pods/perllinux.pod index c02ddd3fa1e..2f9943c2240 100644 --- a/Master/tlpkg/tlperl/lib/pods/perllinux.pod +++ b/Master/tlpkg/tlperl/lib/pods/perllinux.pod @@ -13,7 +13,7 @@ version 5 (hereafter just Perl) is compiled and/or runs. =head2 Experimental Support for Sun Studio Compilers for Linux OS -Sun Microsystems has released a port of their Sun Studio compiliers for +Sun Microsystems has released a port of their Sun Studio compilers for Linux. As of November 2005, only an alpha version has been released. Until a release of these compilers is made, support for compiling Perl with these compiler experimental. diff --git a/Master/tlpkg/tlperl/lib/pods/perllocale.pod b/Master/tlpkg/tlperl/lib/pods/perllocale.pod index 0dbabe7d401..8926d8bc813 100644 --- a/Master/tlpkg/tlperl/lib/pods/perllocale.pod +++ b/Master/tlpkg/tlperl/lib/pods/perllocale.pod @@ -4,13 +4,16 @@ perllocale - Perl locale handling (internationalization and localization) =head1 DESCRIPTION +Locales these days have been mostly been supplanted by Unicode, but Perl +continues to support them. See L</Unicode and UTF-8> below. + Perl supports language-specific notions of data such as "is this a letter", "what is the uppercase equivalent of this letter", and "which of these letters comes first". These are important issues, especially for languages other than English--but also for English: it would be naE<iuml>ve to imagine that C<A-Za-z> defines all the "letters" -needed to write in English. Perl is also aware that some character other -than '.' may be preferred as a decimal point, and that output date +needed to write correct English. Perl is also aware that some character other +than "." may be preferred as a decimal point, and that output date representations may be language-specific. The process of making an application take account of its users' preferences in such matters is called B<internationalization> (often abbreviated as B<i18n>); telling @@ -69,13 +72,13 @@ appropriate, and B<at least one> of the following must be true: =over 4 -=item * +=item 1 B<The locale-determining environment variables (see L<"ENVIRONMENT">) must be correctly set up> at the time the application is started, either -by yourself or by whoever set up your system account. +by yourself or by whoever set up your system account; or -=item * +=item 2 B<The application must set its own locale> using the method described in L<The setlocale function>. @@ -87,7 +90,20 @@ L<The setlocale function>. =head2 The use locale pragma By default, Perl ignores the current locale. The S<C<use locale>> -pragma tells Perl to use the current locale for some operations: +pragma and the C</l> regular expression modifier tell Perl to use the +current locale for some operations (C</l> for just pattern matching). + +The current locale is set at execution time by +L<setlocale()|/The setlocale function> described below. If that function +hasn't yet been called in the course of the program's execution, the +current locale is that which was determined by the L<"ENVIRONMENT"> in +effect at the start of the program, except that +C<L<LC_NUMERIC|/Category LC_NUMERIC: Numeric Formatting>> is always +initialized to the C locale (mentioned under L<Finding locales>). +If there is no valid environment, the current locale is undefined. It +is likely, but not necessarily, the "C" locale. + +The operations that are affected by locale are: =over 4 @@ -115,8 +131,7 @@ ucfirst(), and lcfirst()) use C<LC_CTYPE> =item * -B<The formatting functions> (printf(), sprintf() and write()) use -C<LC_NUMERIC> +B<Format declarations> (format()) use C<LC_NUMERIC> =item * @@ -176,7 +191,7 @@ subsequent call to setlocale(). If no second argument is provided and the category is LC_ALL, the result is implementation-dependent. It may be a string of -concatenated locales names (separator also implementation-dependent) +concatenated locale names (separator also implementation-dependent) or a single locale name. Please consult your setlocale(3) man page for details. @@ -247,6 +262,8 @@ the POSIX standard. They define the B<default locale> in which every program starts in the absence of locale information in its environment. (The I<default> default locale, if you will.) Its language is (American) English and its character codeset ASCII. +B<Warning>. The C locale delivered by some vendors may not +actually exactly match what the C standard calls for. So beware. B<NOTE>: Not all systems have the "POSIX" locale (not all systems are POSIX-conformant), so use "C" when you need explicitly to specify this @@ -466,9 +483,9 @@ basic category at a time. See L<"ENVIRONMENT"> for a discussion of these. In the scope of S<C<use locale>>, Perl looks to the C<LC_COLLATE> environment variable to determine the application's notions on collation -(ordering) of characters. For example, 'b' follows 'a' in Latin -alphabets, but where do 'E<aacute>' and 'E<aring>' belong? And while -'color' follows 'chocolate' in English, what about in Spanish? +(ordering) of characters. For example, "b" follows "a" in Latin +alphabets, but where do "E<aacute>" and "E<aring>" belong? And while +"color" follows "chocolate" in English, what about in Spanish? The following collations all make sense and you may meet any of them if you "use locale". @@ -551,8 +568,8 @@ which stands for alphanumeric characters--that is, alphabetic, numeric, and including other special characters such as the underscore or hyphen. (Consult L<perlre> for more information about regular expressions.) Thanks to C<LC_CTYPE>, depending on your locale -setting, characters like 'E<aelig>', 'E<eth>', 'E<szlig>', and -'E<oslash>' may be understood as C<\w> characters. +setting, characters like "E<aelig>", "E<eth>", "E<szlig>", and +"E<oslash>" may be understood as C<\w> characters. The C<LC_CTYPE> locale also provides the map used in transliterating characters between lower and uppercase. This affects the case-mapping @@ -568,9 +585,9 @@ to your surprise--that "|" moves from the ispunct() class to isalpha(). B<Note:> A broken or malicious C<LC_CTYPE> locale definition may result in clearly ineligible characters being considered to be alphanumeric by -your application. For strict matching of (mundane) letters and +your application. For strict matching of (mundane) ASCII letters and digits--for example, in command strings--locale-aware applications -should use C<\w> inside a C<no locale> block. See L<"SECURITY">. +should use C<\w> with the C</a> regular expression modifier. See L<"SECURITY">. =head2 Category LC_NUMERIC: Numeric Formatting @@ -579,7 +596,7 @@ locale information, which controls an application's idea of how numbers should be formatted for human readability by the printf(), sprintf(), and write() functions. String-to-numeric conversion by the POSIX::strtod() function is also affected. In most implementations the only effect is to -change the character used for the decimal point--perhaps from '.' to ','. +change the character used for the decimal point--perhaps from "." to ",". These functions aren't aware of such niceties as thousands separation and so on. (See L<The localeconv function> if you care about these things.) @@ -607,7 +624,7 @@ See also L<I18N::Langinfo> and C<RADIXCHAR>. =head2 Category LC_MONETARY: Formatting of monetary amounts -The C standard defines the C<LC_MONETARY> category, but no function +The C standard defines the C<LC_MONETARY> category, but not a function that is affected by its contents. (Those with experience of standards committees will recognize that the working group decided to punt on the issue.) Consequently, Perl takes no notice of it. If you really want @@ -867,7 +884,7 @@ using GNU libc and you can ignore C<LANGUAGE>. However, in the case you are using C<LANGUAGE>: it affects the language of informational, warning, and error messages output by commands (in other words, it's like C<LC_MESSAGES>) but it has higher -priority than L<LC_ALL>. Moreover, it's not a single value but +priority than C<LC_ALL>. Moreover, it's not a single value but instead a "path" (":"-separated list) of I<languages> (not locales). See the GNU C<gettext> library documentation for more information. @@ -936,7 +953,9 @@ always in force, even if the program environment suggested otherwise (see L<The setlocale function>). By default, Perl still behaves this way for backward compatibility. If you want a Perl application to pay attention to locale information, you B<must> use the S<C<use locale>> -pragma (see L<The use locale pragma>) to instruct it to do so. +pragma (see L<The use locale pragma>) or for just pattern matching, the +C</l> regular expression modifier (see L<perlre/Character set +modifiers>) to instruct it to do so. Versions of Perl from 5.002 to 5.003 did use the C<LC_CTYPE> information if available; that is, C<\w> did understand what @@ -967,13 +986,11 @@ system's implementation of the locale system than by Perl. =head2 write() and LC_NUMERIC -Formats are the only part of Perl that unconditionally use information -from a program's locale; if a program's environment specifies an -LC_NUMERIC locale, it is always used to specify the decimal point -character in formatted output. Formatted output cannot be controlled by -C<use locale> because the pragma is tied to the block structure of the -program, and, for historical reasons, formats exist outside that block -structure. +If a program's environment specifies an LC_NUMERIC locale and C<use +locale> is in effect when the format is declared, the locale is used +to specify the decimal point character in formatted output. Formatted +output cannot be controlled by C<use locale> at the time when write() +is called. =head2 Freely available locale definitions @@ -1002,17 +1019,61 @@ criticized as incomplete, ungainly, and having too large a granularity. to have them apply to a single thread, window group, or whatever.) They also have a tendency, like standards groups, to divide the world into nations, when we all know that the world can equally well be divided -into bankers, bikers, gamers, and so on. But, for now, it's the only -standard we've got. This may be construed as a bug. +into bankers, bikers, gamers, and so on. =head1 Unicode and UTF-8 -The support of Unicode is new starting from Perl version 5.6, and -more fully implemented in the version 5.8. See L<perluniintro> and -L<perlunicode> for more details. - -Usually locale settings and Unicode do not affect each other, but -there are exceptions, see L<perlunicode/Locales> for examples. +The support of Unicode is new starting from Perl version 5.6, and more fully +implemented in version 5.8 and later. See L<perluniintro>. Perl tries to +work with both Unicode and locales--but of course, there are problems. + +Perl does not handle multi-byte locales, such as have been used for various +Asian languages, such as Big5 or Shift JIS. However, the increasingly common +multi-byte UTF-8 locales, if properly implemented, tend to work +reasonably well in Perl, simply because both they and Perl store +characters that take up multiple bytes the same way. + +Perl generally takes the tack to use locale rules on code points that can fit +in a single byte, and Unicode rules for those that can't (though this wasn't +uniformly applied prior to Perl 5.14). This prevents many problems in locales +that aren't UTF-8. Suppose the locale is ISO8859-7, Greek. The character at +0xD7 there is a capital Chi. But in the ISO8859-1 locale, Latin1, it is a +multiplication sign. The POSIX regular expression character class +C<[[:alpha:]]> will magically match 0xD7 in the Greek locale but not in the +Latin one, even if the string is encoded in UTF-8, which would normally imply +Unicode semantics. (The "U" in UTF-8 stands for Unicode.) + +However, there are places where this breaks down. Certain constructs are +for Unicode only, such as C<\p{Alpha}>. They assume that 0xD7 always has its +Unicode meaning (or the equivalent on EBCDIC platforms). Since Latin1 is a +subset of Unicode and 0xD7 is the multiplication sign in both Latin1 and +Unicode, C<\p{Alpha}> will never match it, regardless of locale. A similar +issue occurs with C<\N{...}>. It is therefore a bad idea to use C<\p{}> or +C<\N{}> under C<use locale>--I<unless> you can guarantee that the locale will +be a ISO8859-1 or UTF-8 one. Use POSIX character classes instead. + + +The same problem ensues if you enable automatic UTF-8-ification of your +standard file handles, default C<open()> layer, and C<@ARGV> on non-ISO8859-1, +non-UTF-8 locales (by using either the B<-C> command line switch or the +C<PERL_UNICODE> environment variable; see L<perlrun>). +Things are read in as UTF-8, which would normally imply a Unicode +interpretation, but the presence of a locale causes them to be interpreted +in that locale instead. For example, a 0xD7 code point in the Unicode +input, which should mean the multiplication sign, won't be interpreted by +Perl that way under the Greek locale. Again, this is not a problem +I<provided> you make certain that all locales will always and only be either +an ISO8859-1 or a UTF-8 locale. + +Vendor locales are notoriously buggy, and it is difficult for Perl to test +its locale-handling code because this interacts with code that Perl has no +control over; therefore the locale-handling code in Perl may be buggy as +well. But if you I<do> have locales that work, using them may be +worthwhile for certain specific purposes, as long as you keep in mind the +gotchas already mentioned. For example, collation runs faster under +locales than under L<Unicode::Collate> (albeit with less flexibility), and +you gain access to such things as the local currency symbol and the names +of the months and days of the week. =head1 BUGS @@ -1020,10 +1081,10 @@ there are exceptions, see L<perlunicode/Locales> for examples. In certain systems, the operating system's locale support is broken and cannot be fixed or used by Perl. Such deficiencies can -and will result in mysterious hangs and/or Perl core dumps when the +and will result in mysterious hangs and/or Perl core dumps when C<use locale> is in effect. When confronted with such a system, please report in excruciating detail to <F<perlbug@perl.org>>, and -complain to your vendor: bug fixes may exist for these problems +also contact your vendor: bug fixes may exist for these problems in your operating system. Sometimes such bug fixes are called an operating system upgrade. @@ -1041,6 +1102,4 @@ L<POSIX/strtod>, L<POSIX/strxfrm>. Jarkko Hietaniemi's original F<perli18n.pod> heavily hacked by Dominic Dunlop, assisted by the perl5-porters. Prose worked over a bit by -Tom Christiansen. - -Last update: Thu Jun 11 08:44:13 MDT 1998 +Tom Christiansen, and updated by Perl 5 porters. diff --git a/Master/tlpkg/tlperl/lib/pods/perllol.pod b/Master/tlpkg/tlperl/lib/pods/perllol.pod index 58d532b12fc..8c6c0563f89 100644 --- a/Master/tlpkg/tlperl/lib/pods/perllol.pod +++ b/Master/tlpkg/tlperl/lib/pods/perllol.pod @@ -6,23 +6,24 @@ perllol - Manipulating Arrays of Arrays in Perl =head2 Declaration and Access of Arrays of Arrays -The simplest thing to build is an array of arrays (sometimes imprecisely -called a list of lists). It's reasonably easy to understand, and -almost everything that applies here will also be applicable later -on with the fancier data structures. +The simplest two-level data structure to build in Perl is an array of +arrays, sometimes casually called a list of lists. It's reasonably easy to +understand, and almost everything that applies here will also be applicable +later on with the fancier data structures. An array of an array is just a regular old array @AoA that you can get at with two subscripts, like C<$AoA[3][2]>. Here's a declaration of the array: + use 5.010; # so we can use say() + # assign to our array, an array of array references @AoA = ( - [ "fred", "barney" ], - [ "george", "jane", "elroy" ], - [ "homer", "marge", "bart" ], + [ "fred", "barney", "pebbles", "bambam", "dino", ], + [ "george", "jane", "elroy", "judy", ], + [ "homer", "bart", "marge", "maggie", ], ); - - print $AoA[2][2]; + say $AoA[2][1]; bart Now you should be very careful that the outer bracket type @@ -33,11 +34,11 @@ but rather just a reference to it, you could do something more like this: # assign a reference to array of array references $ref_to_AoA = [ [ "fred", "barney", "pebbles", "bambam", "dino", ], - [ "homer", "bart", "marge", "maggie", ], [ "george", "jane", "elroy", "judy", ], + [ "homer", "bart", "marge", "maggie", ], ]; - - print $ref_to_AoA->[2][2]; + say $ref_to_AoA->[2][1]; + bart Notice that the outer bracket type has changed, and so our access syntax has also changed. That's because unlike C, in perl you can't freely @@ -88,16 +89,18 @@ array in it. $AoA[$i] = [ @tmp ]; } -It's very important that you make sure to use the C<[]> array reference -constructor. That's because this will be very wrong: +It's important you make sure to use the C<[ ]> array reference +constructor. That's because this wouldn't work: - $AoA[$i] = @tmp; + $AoA[$i] = @tmp; # WRONG! -You see, assigning a named array like that to a scalar just counts the -number of elements in @tmp, which probably isn't what you want. +The reason that doesn't do what you want is because assigning a +named array like that to a scalar is taking an array in scalar +context, which means just counts the number of elements in @tmp. -If you are running under C<use strict>, you'll have to add some -declarations to make it happy: +If you are running under C<use strict> (and if you aren't, why in +the world aren't you?), you'll have to add some declarations to +make it happy: use strict; my(@AoA, @tmp); @@ -118,14 +121,14 @@ if you knew where you wanted to put it: my (@AoA, $i, $line); for $i ( 0 .. 10 ) { $line = <>; - $AoA[$i] = [ split ' ', $line ]; + $AoA[$i] = [ split " ", $line ]; } or even just my (@AoA, $i); for $i ( 0 .. 10 ) { - $AoA[$i] = [ split ' ', <> ]; + $AoA[$i] = [ split " ", <> ]; } You should in general be leery of using functions that could @@ -134,7 +137,7 @@ such. This would be clearer to the casual reader: my (@AoA, $i); for $i ( 0 .. 10 ) { - $AoA[$i] = [ split ' ', scalar(<>) ]; + $AoA[$i] = [ split " ", scalar(<>) ]; } If you wanted to have a $ref_to_AoA variable as a reference to an array, @@ -165,14 +168,45 @@ If you wanted just to append to a row, you'd have to do something a bit funnier looking: # add new columns to an existing row - push @{ $AoA[0] }, "wilma", "betty"; + push @{ $AoA[0] }, "wilma", "betty"; # explicit deref + +Prior to Perl 5.14, this wouldn't even compile: + + push $AoA[0], "wilma", "betty"; # implicit deref + +How come? Because once upon a time, the argument to push() had to be be a +real array, not just a reference to one. That's no longer true. In fact, +the line marked "implicit deref" above works just fine--in this +instance--to do what the one that says explicit deref did. + +The reason I said "in this instance" is because that I<only> works +because C<$AoA[0]> already held an array reference. If you try that on an +undefined variable, you'll take an exception. That's because the implicit +derefererence will never autovivify an undefined variable the way C<@{ }> +always will: -Notice that I I<couldn't> say just: + my $aref = undef; + push $aref, qw(some more values); # WRONG! + push @$aref, qw(a few more); # ok - push $AoA[0], "wilma", "betty"; # WRONG! +If you want to take advantage of this new implicit dereferencing behavior, +go right ahead: it makes code easier on the eye and wrist. Just understand +that older releases will choke on it during compilation. Whenever you make +use of something that works only in some given release of Perl and later, +but not earlier, you should place a prominent -In fact, that wouldn't even compile. How come? Because the argument -to push() must be a real array, not just a reference to such. + use v5.14; # needed for implicit deref of array refs by array ops + +directive at the top of the file that needs it. That way when somebody +tries to run the new code under an old perl, rather than getting an error like + + Type of arg 1 to push must be array (not array element) at /tmp/a line 8, near ""betty";" + Execution of /tmp/a aborted due to compilation errors. + +they'll be politely informed that + + Perl v5.14.0 required--this is only v5.12.3, stopped at /tmp/a line 1. + BEGIN failed--compilation aborted at /tmp/a line 1. =head2 Access and Printing @@ -194,20 +228,20 @@ using the shell-style for() construct to loop across the outer set of subscripts. for $aref ( @AoA ) { - print "\t [ @$aref ],\n"; + say "\t [ @$aref ],"; } If you wanted to keep track of subscripts, you might do this: for $i ( 0 .. $#AoA ) { - print "\t elt $i is [ @{$AoA[$i]} ],\n"; + say "\t elt $i is [ @{$AoA[$i]} ],"; } or maybe even this. Notice the inner loop. for $i ( 0 .. $#AoA ) { for $j ( 0 .. $#{$AoA[$i]} ) { - print "elt $i $j is $AoA[$i][$j]\n"; + say "elt $i $j is $AoA[$i][$j]"; } } @@ -217,7 +251,7 @@ sometimes is easier to take a temporary on your way through: for $i ( 0 .. $#AoA ) { $aref = $AoA[$i]; for $j ( 0 .. $#{$aref} ) { - print "elt $i $j is $AoA[$i][$j]\n"; + say "elt $i $j is $AoA[$i][$j]"; } } @@ -227,18 +261,65 @@ Hmm... that's still a bit ugly. How about this: $aref = $AoA[$i]; $n = @$aref - 1; for $j ( 0 .. $n ) { - print "elt $i $j is $AoA[$i][$j]\n"; + say "elt $i $j is $AoA[$i][$j]"; } } +When you get tired of writing a custom print for your data structures, +you might look at the standard L<Dumpvalue> or L<Data::Dumper> modules. +The former is what the Perl debugger uses, while the latter generates +parsable Perl code. For example: + + use v5.14; # using the + prototype, new to v5.14 + + sub show(+) { + require Dumpvalue; + state $prettily = new Dumpvalue:: + tick => q("), + compactDump => 1, # comment these two lines out + veryCompact => 1, # if you want a bigger dump + ; + dumpValue $prettily @_; + } + + # Assign a list of array references to an array. + my @AoA = ( + [ "fred", "barney" ], + [ "george", "jane", "elroy" ], + [ "homer", "marge", "bart" ], + ); + push $AoA[0], "wilma", "betty"; + show @AoA; + +will print out: + + 0 0..3 "fred" "barney" "wilma" "betty" + 1 0..2 "george" "jane" "elroy" + 2 0..2 "homer" "marge" "bart" + +Whereas if you comment out the two lines I said you might wish to, +then it shows it to you this way instead: + + 0 ARRAY(0x8031d0) + 0 "fred" + 1 "barney" + 2 "wilma" + 3 "betty" + 1 ARRAY(0x803d40) + 0 "george" + 1 "jane" + 2 "elroy" + 2 ARRAY(0x803e10) + 0 "homer" + 1 "marge" + 2 "bart" + =head2 Slices If you want to get at a slice (part of a row) in a multidimensional array, you're going to have to do some fancy subscripting. That's because while we have a nice synonym for single elements via the pointer arrow for dereferencing, no such convenience exists for slices. -(Remember, of course, that you can always write a loop to do a slice -operation.) Here's how to do one operation using a loop. We'll assume an @AoA variable as before. @@ -251,9 +332,13 @@ variable as before. That same loop could be replaced with a slice operation: + @part = @{$AoA[4]}[7..12]; + +or spaced out a bit: + @part = @{ $AoA[4] } [ 7..12 ]; -but as you might well imagine, this is pretty rough on the reader. +But as you might well imagine, this can get pretty rough on the reader. Ah, but what if you wanted a I<two-dimensional slice>, such as having $x run from 4..8 and $y run from 7 to 12? Hmm... here's the simple way: @@ -300,4 +385,4 @@ L<perldata>, L<perlref>, L<perldsc> Tom Christiansen <F<tchrist@perl.com>> -Last update: Thu Jun 4 16:16:23 MDT 1998 +Last update: Tue Apr 26 18:30:55 MDT 2011 diff --git a/Master/tlpkg/tlperl/lib/pods/perlmacos.pod b/Master/tlpkg/tlperl/lib/pods/perlmacos.pod index 8c0a66fa601..ba7d78a2784 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlmacos.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlmacos.pod @@ -8,27 +8,23 @@ README.macos - Perl under Mac OS (Classic) =head1 SYNOPSIS -This document briefly describes perl under Mac OS (Classic). -If you are running perl under Mac OS X, you don't want to be -here (unless you are in the Classic environment under early versions of -Mac OS X). +For Mac OS X see README.macosx + +Perl under Mac OS Classic has not been supported since before Perl 5.10 +(April 2004). When we say "Mac OS" below, we mean Mac OS 7, 8, and 9, and I<not> Mac OS X. - =head1 DESCRIPTION The port of Perl to to Mac OS was officially removed as of Perl 5.12, -though the last offical production release of MacPerl corresponded to +though the last official production release of MacPerl corresponded to Perl 5.6. While Perl 5.10 included the port to Mac OS, ExtUtils::MakeMaker, a core part of Perl's module installation infrastructure officially dropped support for Mac OS in April 2004. -Historical information (and working binaries of the last released version) -are available from L<http://dev.macperl.org> as of October 2009. - =head1 AUTHOR -perl was ported to Mac OS by Matthias Neeracher +Perl was ported to Mac OS by Matthias Neeracher E<lt>neeracher@mac.comE<gt>. Chris Nandor E<lt>pudge@pobox.comE<gt> continued development and maintenance for the duration of the port's life. diff --git a/Master/tlpkg/tlperl/lib/pods/perlmacosx.pod b/Master/tlpkg/tlperl/lib/pods/perlmacosx.pod index a0b21af8c7b..2ba5b1becdb 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlmacosx.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlmacosx.pod @@ -8,14 +8,25 @@ README.macosx - Perl under Mac OS X =head1 SYNOPSIS -This document briefly describes perl under Mac OS X. +This document briefly describes Perl under Mac OS X. + curl http://www.cpan.org/src/perl-5.12.3.tar.gz > perl-5.12.3.tar.gz + tar -xzf perl-5.12.3.tar.gz + cd perl-5.12.3 + ./Configure -des -Dprefix=/usr/local/ + make + make test + sudo make install =head1 DESCRIPTION -The latest Perl release (5.8.8 as of this writing) builds without changes -under Mac OS X. Under 10.3 "Panther" and newer OS versions, all self-tests -pass, and all standard features are supported. +The latest Perl release (5.12.3 as of this writing) builds without changes +under all versions of Mac OS X from 10.3 "Panther" onwards. + +In order to build your own version of Perl you will need 'make' +this is part of the Apples developer tools (you only need the 'unix tools'), +usually supplied with Mac OS install DVDs. You do not need the latest +version of Xcode (which is now charged for) in order to install make. Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a completely thread-safe libc, so threading is not fully supported. Also, @@ -93,7 +104,7 @@ omitted or buggy. Note the messages output by F<Configure> for further information. Please use C<perlbug> to submit a problem report in the event that you encounter difficulties. -When building 64-bit modules, it is your responsiblity to ensure that linked +When building 64-bit modules, it is your responsibility to ensure that linked external libraries and frameworks provide 64-bit support: if they do not, module building may appear to succeed, but attempts to use the module will result in run-time dynamic linking errors, and subsequent test failures. @@ -179,35 +190,10 @@ but remember that there's a startup cost to pay in that case (see above Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for the eu_ES locale (Basque-Spain). In previous releases of Perl, this resulted in -failures in the C<lib/locale> test. These failures have been supressed +failures in the C<lib/locale> test. These failures have been suppressed in the current release of Perl by making the test ignore the broken locale. If you need to use the eu_ES locale, you should contact Apple support. -=head2 MacPerl - -Quite a bit has been written about MacPerl, the Perl distribution for -"Classic MacOS" - that is, versions 9 and earlier of MacOS. Because it -runs in environment that's very different from that of UNIX, many things -are done differently in MacPerl. Modules are installed using a different -procedure, Perl itself is built differently, path names are different, -etc. - -From the perspective of a Perl programmer, Mac OS X is more like a -traditional UNIX than Classic MacOS. If you find documentation that -refers to a special procedure that's needed for MacOS that's drastically -different from the instructions provided for UNIX, the MacOS -instructions are quite often intended for MacPerl on Classic MacOS. In -that case, the correct procedure on Mac OS X is usually to follow the -UNIX instructions, rather than the MacPerl instructions. - - -=head2 Carbon - -MacPerl ships with a number of modules that are used to access the -classic MacOS toolbox. Many of these modules have been updated to use -Mac OS X's newer "Carbon" toolbox, and are available from CPAN in the -"Mac::Carbon" module. - =head2 Cocoa diff --git a/Master/tlpkg/tlperl/lib/pods/perlmod.pod b/Master/tlpkg/tlperl/lib/pods/perlmod.pod index eaa8ba91dbf..5266f199df0 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlmod.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlmod.pod @@ -66,7 +66,7 @@ main, but we decided it was more useful for package writers to be able to use leading underscore to indicate private variables and method names. However, variables and functions named with a single C<_>, such as $_ and C<sub _>, are still forced into the package C<main>. See also -L<perlvar/"Technical Note on the Syntax of Variable Names">. +L<perlvar/"The Syntax of Variable Names">. C<eval>ed strings are compiled in the package in which the eval() was compiled. (Assignments to C<$SIG{}>, however, assume the signal @@ -294,6 +294,9 @@ value of the program. Beware of changing C<$?> by accident (e.g. by running something via C<system>). X<$?> +Inside of a C<END> block, the value of C<${^GLOBAL_PHASE}> will be +C<"END">. + C<UNITCHECK>, C<CHECK> and C<INIT> code blocks are useful to catch the transition between the compilation phase and the execution phase of the main program. @@ -304,17 +307,25 @@ compilation units, as are string C<eval>s, code compiled using the C<(?{ })> construct in a regex, calls to C<do FILE>, C<require FILE>, and code after the C<-e> switch on the command line. +C<BEGIN> and C<UNITCHECK> blocks are not directly related to the phase of +the interpreter. They can be created and executed during any phase. + C<CHECK> code blocks are run just after the B<initial> Perl compile phase ends and before the run time begins, in LIFO order. C<CHECK> code blocks are used in the Perl compiler suite to save the compiled state of the program. +Inside of a C<CHECK> block, the value of C<${^GLOBAL_PHASE}> will be +C<"CHECK">. + C<INIT> blocks are run just before the Perl runtime begins execution, in "first in, first out" (FIFO) order. -The C<CHECK> and C<INIT> code blocks will not be executed inside a string -eval(), if that eval() happens after the end of the main compilation -phase; that can be a problem in mod_perl and other persistent environments -which use C<eval STRING> to load code at runtime. +Inside of an C<INIT> block, the value of C<${^GLOBAL_PHASE}> will be C<"INIT">. + +The C<CHECK> and C<INIT> blocks in code compiled by C<require>, string C<do>, +or string C<eval> will not be executed if they occur after the end of the +main compilation phase; that can be a problem in mod_perl and other persistent +environments which use those functions to load code at runtime. When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and C<END> work just as they do in B<awk>, as a degenerate case. @@ -560,7 +571,7 @@ like for example handle the cloning of non-Perl data, if necessary. C<CLONE> will be called once as a class method for every package that has it defined (or inherits it). It will be called in the context of the new thread, so all modifications are made in the new area. Currently CLONE is called with -no parameters other than the invocant package name, but code should not assume +no parameters other than the invocand package name, but code should not assume that this will remain unchanged, as it is likely that in future extra parameters will be passed in to give more information about the state of cloning. @@ -576,13 +587,13 @@ For example: if in the parent there are two references to a single blessed hash, then in the child there will be two references to a single undefined scalar value instead. This provides a simple mechanism for making a module threadsafe; just add -C<sub CLONE_SKIP { 1 }> at the top of the class, and C<DESTROY()> will be +C<sub CLONE_SKIP { 1 }> at the top of the class, and C<DESTROY()> will now only be called once per object. Of course, if the child thread needs to make use of the objects, then a more sophisticated approach is needed. Like C<CLONE>, C<CLONE_SKIP> is currently called with no parameters other -than the invocant package name, although that may change. Similarly, to +than the invocand package name, although that may change. Similarly, to allow for future expansion, the return value should be a single C<0> or C<1> value. diff --git a/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod b/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod index 05c2dd5c72b..c7148c0550d 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod @@ -97,7 +97,7 @@ Force byte semantics rather than character semantics =item charnames -Define character names for C<\N{named}> string literal escapes +Access to Unicode character names and named character sequences; also define character names =item constant @@ -347,7 +347,7 @@ CGI routines for writing to the HTTPD (or other) error log =item CGI::Cookie -Interface to Netscape Cookies +Interface to HTTP Cookies =item CGI::Fast @@ -393,6 +393,38 @@ Utility for CPAN::Config file Initialization Interface between CPAN.pm and Kwalify.pm +=item CPAN::Meta + +The distribution metadata for a CPAN dist + +=item CPAN::Meta::Converter + +Convert CPAN distribution metadata structures + +=item CPAN::Meta::Feature + +An optional feature provided by a CPAN distribution + +=item CPAN::Meta::History + +History of CPAN Meta Spec changes + +=item CPAN::Meta::Prereqs + +A set of distribution prerequisites by phase and type + +=item CPAN::Meta::Spec + +Specification for CPAN distribution metadata + +=item CPAN::Meta::Validator + +Validate CPAN distribution metadata structures + +=item CPAN::Meta::YAML + +Read and write a subset of YAML for CPAN Meta files + =item CPAN::Nox Wrapper around CPAN.pm without using any XS module @@ -439,11 +471,7 @@ Documentation on how to write your own plugins =item Carp -Warn of errors (from perspective of caller) - -=item Class::ISA - -Report the search path for a class's ISA tree +Alternative warn and die for modules =item Class::Struct @@ -515,7 +543,7 @@ Stringified perl data structures, suitable for both printing and C<eval> =item Devel::DProf -A Perl code profiler +A B<DEPRECATED> Perl code profiler =item Devel::InnerPackage @@ -821,6 +849,10 @@ Frequently Asked Questions About MakeMaker Writing a module with MakeMaker +=item ExtUtils::MakeMaker::YAML + +Clone of YAML::Tiny + =item ExtUtils::Manifest Utilities to write and check a MANIFEST file @@ -973,6 +1005,10 @@ Extended processing of command line options Process single-character switches with switch clustering +=item HTTP::Tiny + +A small, simple, correct HTTP/1.1 client + =item Hash::Util A selection of general-utility hash subroutines @@ -1137,6 +1173,14 @@ SysV Shared Memory IPC object class System V IPC constants and system calls +=item JSON::PP + +JSON::XS compatible pure-Perl module. + +=item JSON::PP::Boolean + +Dummy module providing JSON::PP::Boolean + =item List::Util A selection of general-utility list subroutines @@ -1145,26 +1189,62 @@ A selection of general-utility list subroutines Indicate if List::Util was compiled with a C compiler +=item Locale::Codes + +A distribution of modules to handle locale codes + +=item Locale::Codes::Changes + +Details important changes after 2.07 + +=item Locale::Codes::Country + +Country codes for the Locale::Country module + +=item Locale::Codes::Currency + +Currency codes for the Locale::Currency module + +=item Locale::Codes::Language + +Language codes for the Locale::Language module + +=item Locale::Codes::Script + +Script codes for the Locale::Script module + =item Locale::Constants Constants for Locale codes =item Locale::Country -ISO codes for country identification (ISO 3166) +Standard codes for country identification =item Locale::Currency -ISO three letter codes for currency identification (ISO 4217) +Standard codes for currency identification =item Locale::Language -ISO two letter codes for language identification (ISO 639) +Standard codes for language identification =item Locale::Maketext Framework for localization +=item Locale::Maketext::Cookbook + +Recipes for using Locale::Maketext + +=item Locale::Maketext::Guts + +Deprecated module to load Locale::Maketext utf8 code + +=item Locale::Maketext::GutsLoader + +Deprecated module to load Locale::Maketext utf8 code + =item Locale::Maketext::Simple Simple interface to Locale::Maketext::Lexicon @@ -1175,7 +1255,7 @@ Article about software localization =item Locale::Script -ISO codes for script identification (ISO 15924) +Standard codes for script identification =item Log::Message @@ -1303,7 +1383,7 @@ Examples of Module::Build Usage =item Module::Build::ModuleInfo -Gather package and POD information from a perl module file +DEPRECATED =item Module::Build::Notes @@ -1369,6 +1449,14 @@ Builder class for Mac OS X platform Builder class for OS/2 platform +=item Module::Build::Version + +DEPRECATED + +=item Module::Build::YAML + +DEPRECATED + =item Module::CoreList What modules shipped with versions of perl @@ -1385,6 +1473,10 @@ Looking up module information / loading at runtime Mark modules as loaded or unloaded +=item Module::Metadata + +Gather package and POD information from perl module files + =item Module::Pluggable Automatically give your module the ability to have plugins @@ -1491,7 +1583,11 @@ A generic input parsing/checking mechanism. =item Parse::CPAN::Meta -Parse META.yml and other similar CPAN metadata files +Parse META.yml and META.json CPAN metadata files + +=item Perl::OSType + +Map Perl operating system names to generic types =item PerlIO @@ -1605,10 +1701,6 @@ Let Perldoc render Pod as XML Convert POD data to formatted ASCII text -=item Pod::Plainer - -Perl extension for converting Pod to old-style Pod. - =item Pod::Select Extract selected sections of POD from input @@ -1753,10 +1845,6 @@ Load the C socket.h defines and structure manipulators Persistence for Perl data structures -=item Switch - -A switch statement for Perl - =item Symbol Manipulate Perl symbols and their names @@ -1777,13 +1865,13 @@ Win32 support for Sys::Syslog Base class that provides common functionality to L<TAP::Parser> -=item TAP::Formatter::Color +=item TAP::Formatter::Base -Run Perl test scripts with color +Base class for harness output delegates -=item TAP::Formatter::Console +=item TAP::Formatter::Color -Harness output delegate for default console output +Run Perl test scripts with color =item TAP::Formatter::Console @@ -1831,23 +1919,23 @@ A grammar for the Test Anything Protocol. =item TAP::Parser::Iterator -Internal base class for TAP::Parser Iterators +Base class for TAP source iterators =item TAP::Parser::Iterator::Array -Internal TAP::Parser array Iterator +Iterator for array-based TAP sources =item TAP::Parser::Iterator::Process -Internal TAP::Parser Iterator +Iterator for process-based TAP sources =item TAP::Parser::Iterator::Stream -Internal TAP::Parser Iterator +Iterator for filehandle-based TAP sources =item TAP::Parser::IteratorFactory -Internal TAP::Parser Iterator +Figures out which SourceHandler objects to use for a given Source =item TAP::Parser::Multiplexer @@ -1907,11 +1995,31 @@ A no-op job. =item TAP::Parser::Source -Stream output from some source +A TAP source & meta data about it + +=item TAP::Parser::SourceHandler + +Base class for different TAP source handlers + +=item TAP::Parser::SourceHandler::Executable + +Stream output from an executable TAP source + +=item TAP::Parser::SourceHandler::File + +Stream TAP from a text file. + +=item TAP::Parser::SourceHandler::Handle + +Stream TAP from an IO::Handle or a GLOB. + +=item TAP::Parser::SourceHandler::Perl -=item TAP::Parser::Source::Perl +Stream TAP from a Perl executable -Stream Perl output +=item TAP::Parser::SourceHandler::RawTAP + +Stream output from raw TAP in a scalar/array ref. =item TAP::Parser::Utils @@ -2093,6 +2201,34 @@ Base class for ALL classes (blessed references) Unicode Collation Algorithm +=item Unicode::Collate::CJK::Big5 + +Weighting CJK Unified Ideographs + +=item Unicode::Collate::CJK::GB2312 + +Weighting CJK Unified Ideographs + +=item Unicode::Collate::CJK::JISX0208 + +Weighting JIS KANJI for Unicode::Collate + +=item Unicode::Collate::CJK::Korean + +Weighting CJK Unified Ideographs + +=item Unicode::Collate::CJK::Pinyin + +Weighting CJK Unified Ideographs + +=item Unicode::Collate::CJK::Stroke + +Weighting CJK Unified Ideographs + +=item Unicode::Collate::Locale + +Linguistic tailoring for DUCET via Unicode::Collate + =item Unicode::Normalize Unicode Normalization Forms @@ -2117,6 +2253,10 @@ Perl extension to manipulate DCL symbols Standard I/O functions via VMS extensions +=item Version::Requirements + +A set of version requirements for a CPAN dist + =item Win32 Interfaces to some Win32 API Functions @@ -2133,10 +2273,6 @@ Win32 CORE function stubs Test the perl C API -=item XS::APItest::KeywordRPN - -Write arithmetic expressions in RPN - =item XS::Typemap Module to test the XS typemaps distributed with perl @@ -3397,6 +3533,8 @@ old behavior if people rely on it. Document incompatible changes. =back +=back + =head2 Guidelines for Converting Perl 4 Library Scripts into Modules =over 4 @@ -3495,8 +3633,6 @@ or =back -=back - =head1 NOTE Perl does not enforce private and public parts of its modules as you may diff --git a/Master/tlpkg/tlperl/lib/pods/perlmpeix.pod b/Master/tlpkg/tlperl/lib/pods/perlmpeix.pod index f3cbe8e7bb8..44dea99e10b 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlmpeix.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlmpeix.pod @@ -104,7 +104,7 @@ libwww-perl (LWP) which lets Perl programs behave like web browsers: mod_perl (just the perl portion; the actual DSO will be released soon with Apache/iX 1.3.12 from bixby.org). This module allows you to write high performance persistent Perl CGI scripts and all sorts of -cool things. (http://perl.apache.org/) +cool things. (L<http://perl.apache.org/>) and much much more hiding under /PERL/PUB/.cpan/ @@ -117,7 +117,7 @@ installing of add-on packages: 2. perl -MCPAN -e shell 3. Ignore any terminal I/O related complaints! -(http://search.cpan.org/dist/CPAN/) +(L<http://search.cpan.org/dist/CPAN/>) =back @@ -151,12 +151,12 @@ Migrated from cccd.edu to bixby.org. =head1 Welcome to Perl/iX This is the official home page for the HP e3000 MPE/iX -( http://www.hp.com/go/e3000 ) port of the Perl scripting -language ( http://www.perl.com/ ) which gives you all of the power of C, +( L<http://www.hp.com/go/e3000> ) port of the Perl scripting +language ( L<http://www.perl.com/> ) which gives you all of the power of C, awk, sed, and sh in a single language. Check here for the latest news, implemented functionality, known bugs, to-do list, etc. Status reports about major milestones will also be posted to the HP3000-L mailing list -( http://www.lsoft.com/scripts/wl.exe?SL1=HP3000-L&H=RAVEN.UTC.EDU ) and +( L<http://www.lsoft.com/scripts/wl.exe?SL1=HP3000-L&H=RAVEN.UTC.EDU> ) and its associated gatewayed newsgroup comp.sys.hp.mpe. I'm doing this port because I can't live without Perl on the Unix @@ -164,14 +164,14 @@ machines that I administer, and I want to have the same power available to me on MPE. Please send your comments, questions, and bug reports directly to me, -Mark Bixby ( http://www.bixby.org/mark/ ). Or just post them to HP3000-L. +Mark Bixby ( L<http://www.bixby.org/mark/> ). Or just post them to HP3000-L. The platform I'm using to do this port is an HP 3000 957RX running MPE/iX 6.0 and using the GNU gcc C compiler -( http://jazz.external.hp.com/src/gnu/gnuframe.html ). +( L<http://jazz.external.hp.com/src/gnu/gnuframe.html> ). The combined porting wisdom from all of my ports can be found in my -MPE/iX Porting Guide (http://www.bixby.org/mark/porting.html). +MPE/iX Porting Guide (L<http://www.bixby.org/mark/porting.html>). IMPORTANT NOTICE: Yes, I do work for the HP CSY R&D lab, but ALL of the software you download from bixby.org is my personal freeware that @@ -189,7 +189,7 @@ MPE/iX 5.0 or earlier, nor does it run on "classic" MPE/V machines. =item * If you wish to recompile Perl, you must install both GNUCORE and -GNUGCC from jazz (http://jazz.external.hp.com/src/gnu/gnuframe.html). +GNUGCC from jazz (L<http://jazz.external.hp.com/src/gnu/gnuframe.html>). =item * @@ -205,9 +205,9 @@ to _getenv_libc. =item * If you will be compiling Perl/iX yourself, you will also need -Syslog/iX ( http://www.bixby.org/mark/syslogix.html ) and the +Syslog/iX ( L<http://www.bixby.org/mark/syslogix.html> ) and the /BIND/PUB/include and /BIND/PUB/lib portions of BIND/iX -( http://www.bixby.org/mark/bindix.html ). +( L<http://www.bixby.org/mark/bindix.html> ). =back @@ -418,9 +418,9 @@ equivalent symbolic link) as the first line. Use the chmod command to make sure that your script has execute permission. Run your script! Be sure to take a look at the CPAN module list -( http://www.cpan.org/CPAN.html ). A wide variety of free Perl software +( L<http://www.cpan.org/CPAN.html> ). A wide variety of free Perl software is available. You can automatically download these packages by using -the CPAN module ( http://search.cpan.org/dist/CPAN/ ). +the CPAN module ( L<http://search.cpan.org/dist/CPAN/> ). =head1 MPE/iX Implementation Considerations @@ -707,5 +707,5 @@ Porting begins. =head1 AUTHOR -Mark Bixby, http://www.bixby.org/mark/ +Mark Bixby, L<http://www.bixby.org/mark/> diff --git a/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod b/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod index 2200becded2..74bd9b2a77d 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod @@ -54,8 +54,12 @@ function - the parameter is provided to allow your implementation to track depth if it needs to recurse. The function should return a reference to an array containing the parent -classes in order. The caller is responsible for incrementing the reference -count if it wants to keep the structure. Hence if you have created a +classes in order. The names of the classes should be the result of calling +C<HvENAME()> on the stash. In those cases where C<HvENAME()> returns null, +C<HvNAME()> should be used instead. + +The caller is responsible for incrementing the reference count of the array +returned if it wants to keep the structure. Hence, if you have created a temporary value that you keep no pointer to, C<sv_2mortal()> to ensure that it is disposed of correctly. If you have cached your return value, then return a pointer to it without changing the reference count. diff --git a/Master/tlpkg/tlperl/lib/pods/perlnetware.pod b/Master/tlpkg/tlperl/lib/pods/perlnetware.pod index 1e92b84890a..6720a58212a 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlnetware.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlnetware.pod @@ -48,14 +48,25 @@ sets the build type to Release by default. This is used to set the build type to debug or release. Change the build type only after executing SetNWBld.bat -=item * - Example: - 1. Typing "buildtype d on" at the command prompt causes the buildtype - to be set to Debug type with D2 flag set. - 2. Typing "buildtype d off" or "buildtype d" at the command prompt causes - the buildtype to be set to Debug type with D1 flag set. - 2. Typing "buildtype r" at the command prompt sets it to Release Build type. + +=over + +=item 1. + +Typing "buildtype d on" at the command prompt causes the buildtype +to be set to Debug type with D2 flag set. + +=item 2. + +Typing "buildtype d off" or "buildtype d" at the command prompt causes +the buildtype to be set to Debug type with D1 flag set. + +=item 3. + +Typing "buildtype r" at the command prompt sets it to Release Build type. + +=back =back @@ -64,7 +75,7 @@ Example: The make process runs only under WinNT shell. The NetWare makefile is located under the NetWare folder. This makes use of miniperl.exe to run some of the Perl scripts. To create miniperl.exe, first set the -required paths for Visual c++ compilier (specify vcvars32 location) at +required paths for Visual c++ compiler (specify vcvars32 location) at the command prompt. Then run nmake from win32 folder through WinNT command prompt. The build process can be stopped after miniperl.exe is created. Then run nmake from NetWare folder through WinNT command @@ -107,8 +118,8 @@ I<sys:\perl\system> folder. Copy this to I<sys:\system> folder. Example: At the command prompt Type "nmake nwinstall". This will install NetWare Perl on the NetWare Server. - Similiarly if you type "nmake install", - This will cause the binaries to be installed on the local machine. + Similarly, if you type "nmake install", + this will cause the binaries to be installed on the local machine. (Typically under the c:\perl folder) =head1 BUILD NEW EXTENSIONS diff --git a/Master/tlpkg/tlperl/lib/pods/perlobj.pod b/Master/tlpkg/tlperl/lib/pods/perlobj.pod index fdecd84a688..850225f64a9 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlobj.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlobj.pod @@ -576,7 +576,7 @@ destructed. Plain refs are only garbage-collected if the destruct level is greater than 0. You can test the higher levels of global destruction by setting the PERL_DESTRUCT_LEVEL environment variable, presuming C<-DDEBUGGING> was enabled during perl build time. -See L<perlhack/PERL_DESTRUCT_LEVEL> for more information. +See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information. A more complete garbage collection strategy will be implemented at a future date. diff --git a/Master/tlpkg/tlperl/lib/pods/perlop.pod b/Master/tlpkg/tlperl/lib/pods/perlop.pod index ebe32fb3102..665a6b58aba 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlop.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlop.pod @@ -152,7 +152,7 @@ value. Note that just as in C, Perl doesn't define B<when> the variable is incremented or decremented. You just know it will be done sometime before or after the value is returned. This also means that modifying -a variable twice in the same statement will lead to undefined behaviour. +a variable twice in the same statement will lead to undefined behavior. Avoid statements like: $i = $i ++; @@ -168,10 +168,10 @@ has a value that is not the empty string and matches the pattern C</^[a-zA-Z]*[0-9]*\z/>, the increment is done as a string, preserving each character within its range, with carry: - print ++($foo = '99'); # prints '100' - print ++($foo = 'a0'); # prints 'a1' - print ++($foo = 'Az'); # prints 'Ba' - print ++($foo = 'zz'); # prints 'aaa' + print ++($foo = "99"); # prints "100" + print ++($foo = "a0"); # prints "a1" + print ++($foo = "Az"); # prints "Ba" + print ++($foo = "zz"); # prints "aaa" C<undef> is always treated as numeric, and in particular is changed to C<0> before incrementing (so that a post-increment of an undef value @@ -194,11 +194,12 @@ Unary "!" performs logical negation, i.e., "not". See also C<not> for a lower precedence version of this. X<!> -Unary "-" performs arithmetic negation if the operand is numeric. If -the operand is an identifier, a string consisting of a minus sign -concatenated with the identifier is returned. Otherwise, if the string -starts with a plus or minus, a string starting with the opposite sign -is returned. One effect of these rules is that -bareword is equivalent +Unary "-" performs arithmetic negation if the operand is numeric, +including any string that looks like a number. If the operand is +an identifier, a string consisting of a minus sign concatenated +with the identifier is returned. Otherwise, if the string starts +with a plus or minus, a string starting with the opposite sign is +returned. One effect of these rules is that -bareword is equivalent to the string "-bareword". If, however, the string begins with a non-alphabetic character (excluding "+" or "-"), Perl will attempt to convert the string to a numeric and the arithmetic negation is performed. If the @@ -211,9 +212,15 @@ example, C<0666 & ~027> is 0640. (See also L<Integer Arithmetic> and L<Bitwise String Operators>.) Note that the width of the result is platform-dependent: ~0 is 32 bits wide on a 32-bit platform, but 64 bits wide on a 64-bit platform, so if you are expecting a certain bit -width, remember to use the & operator to mask off the excess bits. +width, remember to use the "&" operator to mask off the excess bits. X<~> X<negation, binary> +When complementing strings, if all characters have ordinal values under +256, then their complements will, also. But if they do not, all +characters will be in either 32- or 64-bit complements, depending on your +architecture. So for example, C<~"\x{3B1}"> is C<"\x{FFFF_FC4E}"> on +32-bit machines and C<"\x{FFFF_FFFF_FFFF_FC4E}"> on 64-bit machines. + Unary "+" has no effect whatsoever, even on strings. It is useful syntactically for separating a function name from a parenthesized expression that would otherwise be interpreted as the complete list of function @@ -235,9 +242,12 @@ of operation work on some other string. The right argument is a search pattern, substitution, or transliteration. The left argument is what is supposed to be searched, substituted, or transliterated instead of the default $_. When used in scalar context, the return value generally indicates the -success of the operation. Behavior in list context depends on the particular -operator. See L</"Regexp Quote-Like Operators"> for details and -L<perlretut> for examples using these operators. +success of the operation. The exceptions are substitution (s///) +and transliteration (y///) with the C</r> (non-destructive) option, +which cause the B<r>eturn value to be the result of the substitution. +Behavior in list context depends on the particular operator. +See L</"Regexp Quote-Like Operators"> for details and L<perlretut> for +examples using these operators. If the right argument is an expression rather than a search pattern, substitution, or transliteration, it is interpreted as a search pattern at run @@ -251,6 +261,9 @@ pattern C<\>, which it will consider a syntax error. Binary "!~" is just like "=~" except the return value is negated in the logical sense. +Binary "!~" with a non-destructive substitution (s///r) or transliteration +(y///r) is a syntax error. + =head2 Multiplicative Operators X<operator, multiplicative> @@ -503,17 +516,20 @@ Although it has no direct equivalent in C, Perl's C<//> operator is related to its C-style or. In fact, it's exactly the same as C<||>, except that it tests the left hand side's definedness instead of its truth. Thus, C<$a // $b> is similar to C<defined($a) || $b> (except that it returns the value of C<$a> -rather than the value of C<defined($a)>) and is exactly equivalent to -C<defined($a) ? $a : $b>. This is very useful for providing default values -for variables. If you actually want to test if at least one of C<$a> and -C<$b> is defined, use C<defined($a // $b)>. +rather than the value of C<defined($a)>) and yields the same result as +C<defined($a) ? $a : $b> (except that the ternary-operator form can be +used as a lvalue, while C<$a // $b> cannot). This is very useful for +providing default values for variables. If you actually want to test if +at least one of C<$a> and C<$b> is defined, use C<defined($a // $b)>. The C<||>, C<//> and C<&&> operators return the last value evaluated (unlike C's C<||> and C<&&>, which return 0 or 1). Thus, a reasonably portable way to find out the home directory might be: - $home = $ENV{'HOME'} // $ENV{'LOGDIR'} // - (getpwuid($<))[7] // die "You're homeless!\n"; + $home = $ENV{HOME} + // $ENV{LOGDIR} + // (getpwuid($<))[7] + // die "You're homeless!\n"; In particular, this means that you shouldn't use this for selecting between two aggregates for assignment: @@ -602,7 +618,7 @@ Examples: As a scalar operator: if (101 .. 200) { print; } # print 2nd hundred lines, short for - # if ($. == 101 .. $. == 200) { print; } + # if ($. == 101 .. $. == 200) { print; } next LINE if (1 .. /^$/); # skip header lines, short for # next LINE if ($. == 1 .. /^$/); @@ -651,15 +667,15 @@ The range operator (in list context) makes use of the magical auto-increment algorithm if the operands are strings. You can say - @alphabet = ('A' .. 'Z'); + @alphabet = ("A" .. "Z"); to get all normal letters of the English alphabet, or - $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15]; + $hexdigit = (0 .. 9, "a" .. "f")[$num & 15]; to get a hexadecimal digit, or - @z2 = ('01' .. '31'); print $z2[$mday]; + @z2 = ("01" .. "31"); print $z2[$mday]; to get dates with leading zeros. @@ -668,16 +684,23 @@ increment would produce, the sequence goes until the next value would be longer than the final value specified. If the initial value specified isn't part of a magical increment -sequence (that is, a non-empty string matching "/^[a-zA-Z]*[0-9]*\z/"), +sequence (that is, a non-empty string matching C</^[a-zA-Z]*[0-9]*\z/>), only the initial value will be returned. So the following will only return an alpha: - use charnames 'greek'; + use charnames "greek"; my @greek_small = ("\N{alpha}" .. "\N{omega}"); -To get lower-case greek letters, use this instead: +To get the 25 traditional lowercase Greek letters, including both sigmas, +you could use this instead: - my @greek_small = map { chr } ( ord("\N{alpha}") .. ord("\N{omega}") ); + use charnames "greek"; + my @greek_small = map { chr } + ord "\N{alpha}" .. ord "\N{omega}"; + +However, because there are I<many> other lowercase Greek characters than +just those, to match lowercase Greek characters in a regular expression, +you would use the pattern C</(?:(?=\p{Greek})\p{Lower})+/>. Because each operand is evaluated in integer form, C<2.18 .. 3.14> will return two elements in list context. @@ -693,7 +716,7 @@ argument before the : is returned, otherwise the argument after the : is returned. For example: printf "I have %d dog%s.\n", $n, - ($n == 1) ? '' : "s"; + ($n == 1) ? "" : "s"; Scalar or list context propagates downward into the 2nd or 3rd argument, whichever is selected. @@ -756,7 +779,7 @@ Modifying an assignment is equivalent to doing the assignment and then modifying the variable that was assigned to. This is useful for modifying a copy of something, like this: - ($tmp = $global) =~ tr [A-Z] [a-z]; + ($tmp = $global) =~ tr [0-9] [a-j]; Likewise, @@ -772,6 +795,72 @@ lvalues assigned to, and a list assignment in scalar context returns the number of elements produced by the expression on the right hand side of the assignment. +=head2 The Triple-Dot Operator +X<...> X<... operator> X<yada-yada operator> X<whatever operator> +X<triple-dot operator> + +The triple-dot operator, C<...>, sometimes called the "whatever operator", the +"yada-yada operator", or the "I<et cetera>" operator, is a placeholder for +code. Perl parses it without error, but when you try to execute a whatever, +it throws an exception with the text C<Unimplemented>: + + sub unimplemented { ... } + + eval { unimplemented() }; + if ($@ eq "Unimplemented" ) { + say "Oh look, an exception--whatever."; + } + +You can only use the triple-dot operator to stand in for a complete statement. +These examples of the triple-dot work: + + { ... } + + sub foo { ... } + + ...; + + eval { ... }; + + sub foo { + my ($self) = shift; + ...; + } + + do { + my $variable; + ...; + say "Hurrah!"; + } while $cheering; + +The yada-yada--or whatever--cannot stand in for an expression that is +part of a larger statement since the C<...> is also the three-dot version +of the binary range operator (see L<Range Operators>). These examples of +the whatever operator are still syntax errors: + + print ...; + + open(PASSWD, ">", "/dev/passwd") or ...; + + if ($condition && ...) { say "Hello" } + +There are some cases where Perl can't immediately tell the difference +between an expression and a statement. For instance, the syntax for a +block and an anonymous hash reference constructor look the same unless +there's something in the braces that give Perl a hint. The whatever +is a syntax error if Perl doesn't guess that the C<{ ... }> is a +block. In that case, it doesn't think the C<...> is the whatever +because it's expecting an expression instead of a statement: + + my @transformed = map { ... } @input; # syntax error + +You can use a C<;> inside your block to denote that the C<{ ... }> is +a block and not a hash reference constructor. Now the whatever works: + + my @transformed = map {; ... } @input; # ; disambiguates + + my @transformed = map { ...; } @input; # ; disambiguates + =head2 Comma Operator X<comma> X<operator, comma> X<,> @@ -788,7 +877,7 @@ its left operand to be interpreted as a string if it begins with a letter or underscore and is composed only of letters, digits and underscores. This includes operands that might otherwise be interpreted as operators, constants, single number v-strings or function calls. If in doubt about -this behaviour, the left operand can be quoted explicitly. +this behavior, the left operand can be quoted explicitly. Otherwise, the C<< => >> operator behaves exactly as the comma operator or list argument separator, according to context. @@ -813,78 +902,17 @@ between keys and values in hashes, and other paired elements in lists. %hash = ( $key => $value ); login( $username => $password ); -=head2 Yada Yada Operator -X<...> X<... operator> X<yada yada operator> - -The yada yada operator (noted C<...>) is a placeholder for code. Perl -parses it without error, but when you try to execute a yada yada, it -throws an exception with the text C<Unimplemented>: - - sub unimplemented { ... } - - eval { unimplemented() }; - if( $@ eq 'Unimplemented' ) { - print "I found the yada yada!\n"; - } - -You can only use the yada yada to stand in for a complete statement. -These examples of the yada yada work: - - { ... } - - sub foo { ... } - - ...; - - eval { ... }; - - sub foo { - my( $self ) = shift; - - ...; - } - - do { my $n; ...; print 'Hurrah!' }; - -The yada yada cannot stand in for an expression that is part of a -larger statement since the C<...> is also the three-dot version of the -range operator (see L<Range Operators>). These examples of the yada -yada are still syntax errors: - - print ...; - - open my($fh), '>', '/dev/passwd' or ...; - - if( $condition && ... ) { print "Hello\n" }; - -There are some cases where Perl can't immediately tell the difference -between an expression and a statement. For instance, the syntax for a -block and an anonymous hash reference constructor look the same unless -there's something in the braces that give Perl a hint. The yada yada -is a syntax error if Perl doesn't guess that the C<{ ... }> is a -block. In that case, it doesn't think the C<...> is the yada yada -because it's expecting an expression instead of a statement: - - my @transformed = map { ... } @input; # syntax error - -You can use a C<;> inside your block to denote that the C<{ ... }> is -a block and not a hash reference constructor. Now the yada yada works: - - my @transformed = map {; ... } @input; # ; disambiguates - - my @transformed = map { ...; } @input; # ; disambiguates - =head2 List Operators (Rightward) X<operator, list, rightward> X<list operator> -On the right side of a list operator, it has very low precedence, +On the right side of a list operator, the comma has very low precedence, such that it controls all comma-separated expressions found there. The only operators with lower precedence are the logical operators "and", "or", and "not", which may be used to evaluate calls to list operators without the need for extra parentheses: - open HANDLE, "filename" - or die "Can't open: $!\n"; + open HANDLE, "< $file" + or die "Can't open $file: $!\n"; See also discussion of list operators in L<Terms and List Operators (Leftward)>. @@ -898,8 +926,8 @@ It's the equivalent of "!" except for the very low precedence. X<operator, logical, and> X<and> Binary "and" returns the logical conjunction of the two surrounding -expressions. It's equivalent to && except for the very low -precedence. This means that it short-circuits: i.e., the right +expressions. It's equivalent to C<&&> except for the very low +precedence. This means that it short-circuits: the right expression is evaluated only if the left expression is true. =head2 Logical or, Defined or, and Exclusive Or @@ -908,21 +936,22 @@ X<operator, logical, defined or> X<operator, logical, exclusive or> X<or> X<xor> Binary "or" returns the logical disjunction of the two surrounding -expressions. It's equivalent to || except for the very low precedence. -This makes it useful for control flow +expressions. It's equivalent to C<||> except for the very low precedence. +This makes it useful for control flow: print FH $data or die "Can't write to FH: $!"; -This means that it short-circuits: i.e., the right expression is evaluated -only if the left expression is false. Due to its precedence, you should -probably avoid using this for assignment, only for control flow. +This means that it short-circuits: the right expression is evaluated +only if the left expression is false. Due to its precedence, you must +be careful to avoid using it as replacement for the C<||> operator. +It usually works out better for flow control than in assignments: $a = $b or $c; # bug: this is wrong ($a = $b) or $c; # really means this $a = $b || $c; # better written this way However, when it's a list-context assignment and you're trying to use -"||" for control flow, you probably need "or" so that the assignment +C<||> for control flow, you probably need "or" so that the assignment takes higher precedence. @info = stat($file) || die; # oops, scalar sense of stat! @@ -931,7 +960,7 @@ takes higher precedence. Then again, you could always use parentheses. Binary "xor" returns the exclusive-OR of the two surrounding expressions. -It cannot short circuit, of course. +It cannot short-circuit (of course). =head2 C Operators Missing From Perl X<operator, missing from perl> X<&> X<*> @@ -961,7 +990,6 @@ X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m> X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>> X<escape sequence> X<escape> - While we usually think of quotes as literal values, in Perl they function as operators, providing various kinds of interpolating and pattern matching capabilities. Perl provides customary quote characters @@ -978,27 +1006,27 @@ any pair of delimiters you choose. qr{} Pattern yes* s{}{} Substitution yes* tr{}{} Transliteration no (but see below) + y{}{} Transliteration no (but see below) <<EOF here-doc yes* * unless the delimiter is ''. Non-bracketing delimiters use the same character fore and aft, but the four -sorts of brackets (round, angle, square, curly) will all nest, which means +sorts of ASCII brackets (round, angle, square, curly) all nest, which means that - q{foo{bar}baz} + q{foo{bar}baz} is the same as - 'foo{bar}baz' + 'foo{bar}baz' Note, however, that this does not always work for quoting Perl code: - $s = q{ if($a eq "}") ... }; # WRONG + $s = q{ if($a eq "}") ... }; # WRONG -is a syntax error. The C<Text::Balanced> module (from CPAN, and -starting from Perl 5.8 part of the standard distribution) is able -to do this properly. +is a syntax error. The C<Text::Balanced> module (standard as of v5.8, +and from CPAN before then) is able to do this properly. There can be whitespace between the operator and the quoting characters, except when C<#> is being used as the quoting character. @@ -1009,35 +1037,167 @@ from the next line. This allows you to write: s {foo} # Replace foo {bar} # with bar. -The following escape sequences are available in constructs that interpolate -and in transliterations. -X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N> - - \t tab (HT, TAB) - \n newline (NL) - \r return (CR) - \f form feed (FF) - \b backspace (BS) - \a alarm (bell) (BEL) - \e escape (ESC) - \033 octal char (example: ESC) - \x1b hex char (example: ESC) - \x{263a} wide hex char (example: SMILEY) - \c[ control char (example: ESC) - \N{name} named Unicode character - \N{U+263D} Unicode character (example: FIRST QUARTER MOON) - -The character following C<\c> is mapped to some other character by -converting letters to upper case and then (on ASCII systems) by inverting -the 7th bit (0x40). The most interesting range is from '@' to '_' -(0x40 through 0x5F), resulting in a control character from 0x00 -through 0x1F. A '?' maps to the DEL character. On EBCDIC systems only -'@', the letters, '[', '\', ']', '^', '_' and '?' will work, resulting -in 0x00 through 0x1F and 0x7F. - -C<\N{U+I<wide hex char>}> means the Unicode character whose Unicode ordinal -number is I<wide hex char>. -For documentation of C<\N{name}>, see L<charnames>. +The following escape sequences are available in constructs that interpolate, +and in transliterations: +X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N> X<\N{}> +X<\o{}> + + Sequence Note Description + \t tab (HT, TAB) + \n newline (NL) + \r return (CR) + \f form feed (FF) + \b backspace (BS) + \a alarm (bell) (BEL) + \e escape (ESC) + \x{263A} [1,8] hex char (example: SMILEY) + \x1b [2,8] restricted range hex char (example: ESC) + \N{name} [3] named Unicode character or character sequence + \N{U+263D} [4,8] Unicode character (example: FIRST QUARTER MOON) + \c[ [5] control char (example: chr(27)) + \o{23072} [6,8] octal char (example: SMILEY) + \033 [7,8] restricted range octal char (example: ESC) + +=over 4 + +=item [1] + +The result is the character specified by the hexadecimal number between +the braces. See L</[8]> below for details on which character. + +Only hexadecimal digits are valid between the braces. If an invalid +character is encountered, a warning will be issued and the invalid +character and all subsequent characters (valid or invalid) within the +braces will be discarded. + +If there are no valid digits between the braces, the generated character is +the NULL character (C<\x{00}>). However, an explicit empty brace (C<\x{}>) +will not cause a warning (currently). + +=item [2] + +The result is the character specified by the hexadecimal number in the range +0x00 to 0xFF. See L</[8]> below for details on which character. + +Only hexadecimal digits are valid following C<\x>. When C<\x> is followed +by fewer than two valid digits, any valid digits will be zero-padded. This +means that C<\x7> will be interpreted as C<\x07>, and a lone <\x> will be +interpreted as C<\x00>. Except at the end of a string, having fewer than +two valid digits will result in a warning. Note that although the warning +says the illegal character is ignored, it is only ignored as part of the +escape and will still be used as the subsequent character in the string. +For example: + + Original Result Warns? + "\x7" "\x07" no + "\x" "\x00" no + "\x7q" "\x07q" yes + "\xq" "\x00q" yes + +=item [3] + +The result is the Unicode character or character sequence given by I<name>. +See L<charnames>. + +=item [4] + +C<\N{U+I<hexadecimal number>}> means the Unicode character whose Unicode code +point is I<hexadecimal number>. + +=item [5] + +The character following C<\c> is mapped to some other character as shown in the +table: + + Sequence Value + \c@ chr(0) + \cA chr(1) + \ca chr(1) + \cB chr(2) + \cb chr(2) + ... + \cZ chr(26) + \cz chr(26) + \c[ chr(27) + \c] chr(29) + \c^ chr(30) + \c? chr(127) + +Also, C<\c\I<X>> yields C< chr(28) . "I<X>"> for any I<X>, but cannot come at the +end of a string, because the backslash would be parsed as escaping the end +quote. + +On ASCII platforms, the resulting characters from the list above are the +complete set of ASCII controls. This isn't the case on EBCDIC platforms; see +L<perlebcdic/OPERATOR DIFFERENCES> for the complete list of what these +sequences mean on both ASCII and EBCDIC platforms. + +Use of any other character following the "c" besides those listed above is +discouraged, and some are deprecated with the intention of removing +those in Perl 5.16. What happens for any of these +other characters currently though, is that the value is derived by inverting +the 7th bit (0x40). + +To get platform independent controls, you can use C<\N{...}>. + +=item [6] + +The result is the character specified by the octal number between the braces. +See L</[8]> below for details on which character. + +If a character that isn't an octal digit is encountered, a warning is raised, +and the value is based on the octal digits before it, discarding it and all +following characters up to the closing brace. It is a fatal error if there are +no octal digits at all. + +=item [7] + +The result is the character specified by the three-digit octal number in the +range 000 to 777 (but best to not use above 077, see next paragraph). See +L</[8]> below for details on which character. + +Some contexts allow 2 or even 1 digit, but any usage without exactly +three digits, the first being a zero, may give unintended results. (For +example, see L<perlrebackslash/Octal escapes>.) Starting in Perl 5.14, you may +use C<\o{}> instead, which avoids all these problems. Otherwise, it is best to +use this construct only for ordinals C<\077> and below, remembering to pad to +the left with zeros to make three digits. For larger ordinals, either use +C<\o{}> , or convert to something else, such as to hex and use C<\x{}> +instead. + +Having fewer than 3 digits may lead to a misleading warning message that says +that what follows is ignored. For example, C<"\128"> in the ASCII character set +is equivalent to the two characters C<"\n8">, but the warning C<Illegal octal +digit '8' ignored> will be thrown. To avoid this warning, make sure to pad +your octal number with C<0>'s: C<"\0128">. + +=item [8] + +Several constructs above specify a character by a number. That number +gives the character's position in the character set encoding (indexed from 0). +This is called synonymously its ordinal, code position, or code point. Perl +works on platforms that have a native encoding currently of either ASCII/Latin1 +or EBCDIC, each of which allow specification of 256 characters. In general, if +the number is 255 (0xFF, 0377) or below, Perl interprets this in the platform's +native encoding. If the number is 256 (0x100, 0400) or above, Perl interprets +it as a Unicode code point and the result is the corresponding Unicode +character. For example C<\x{50}> and C<\o{120}> both are the number 80 in +decimal, which is less than 256, so the number is interpreted in the native +character set encoding. In ASCII the character in the 80th position (indexed +from 0) is the letter "P", and in EBCDIC it is the ampersand symbol "&". +C<\x{100}> and C<\o{400}> are both 256 in decimal, so the number is interpreted +as a Unicode code point no matter what the native encoding is. The name of the +character in the 100th position (indexed by 0) in Unicode is +C<LATIN CAPITAL LETTER A WITH MACRON>. + +There are a couple of exceptions to the above rule. C<\N{U+I<hex number>}> is +always interpreted as a Unicode code point, so that C<\N{U+0050}> is "P" even +on EBCDIC platforms. And if L<C<S<use encoding>>|encoding> is in effect, the +number is considered to be in that encoding, and is translated from that into +the platform's native encoding if there is a corresponding native character; +otherwise to Unicode. + +=back B<NOTE>: Unlike C and other languages, Perl has no C<\v> escape sequence for the vertical tab (VT - ASCII 11), but you may use C<\ck> or C<\x0b>. (C<\v> @@ -1047,26 +1207,35 @@ The following escape sequences are available in constructs that interpolate, but not in transliterations. X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q> - \l lowercase next char - \u uppercase next char - \L lowercase till \E - \U uppercase till \E - \E end case modification + \l lowercase next character only + \u titlecase (not uppercase!) next character only + \L lowercase all characters till \E seen + \U uppercase all characters till \E seen \Q quote non-word characters till \E + \E end either case modification or quoted section + (whichever was last seen) + +C<\L>, C<\U>, and C<\Q> can stack, in which case you need one +C<\E> for each. For example: + + say "This \Qquoting \ubusiness \Uhere isn't quite\E done yet,\E is it?"; + This quoting\ Business\ HERE\ ISN\'T\ QUITE\ done\ yet\, is it? If C<use locale> is in effect, the case map used by C<\l>, C<\L>, -C<\u> and C<\U> is taken from the current locale. See L<perllocale>. -If Unicode (for example, C<\N{}> or wide hex characters of 0x100 or -beyond) is being used, the case map used by C<\l>, C<\L>, C<\u> and -C<\U> is as defined by Unicode. +C<\u>, and C<\U> is taken from the current locale. See L<perllocale>. +If Unicode (for example, C<\N{}> or code points of 0x100 or +beyond) is being used, the case map used by C<\l>, C<\L>, C<\u>, and +C<\U> is as defined by Unicode. That means that case-mapping +a single character can sometimes produce several characters. All systems use the virtual C<"\n"> to represent a line terminator, called a "newline". There is no such thing as an unvarying, physical newline character. It is only an illusion that the operating system, device drivers, C libraries, and Perl all conspire to preserve. Not all systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF. For example, -on a Mac, these are reversed, and on systems without line terminator, -printing C<"\n"> may emit no actual data. In general, use C<"\n"> when +on the ancient Macs (pre-MacOS X) of yesteryear, these used to be reversed, +and on systems without line terminator, +printing C<"\n"> might emit no actual data. In general, use C<"\n"> when you mean a "newline" for your system, but use the literal ASCII when you need an exact character. For example, most networking protocols expect and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators, @@ -1083,14 +1252,28 @@ But method calls such as C<< $obj->meth >> are not. Interpolating an array or slice interpolates the elements in order, separated by the value of C<$">, so is equivalent to interpolating -C<join $", @array>. "Punctuation" arrays such as C<@*> are only -interpolated if the name is enclosed in braces C<@{*}>, but special -arrays C<@_>, C<@+>, and C<@-> are interpolated, even without braces. +C<join $", @array>. "Punctuation" arrays such as C<@*> are usually +interpolated only if the name is enclosed in braces C<@{*}>, but the +arrays C<@_>, C<@+>, and C<@-> are interpolated even without braces. + +For double-quoted strings, the quoting from C<\Q> is applied after +interpolation and escapes are processed. -You cannot include a literal C<$> or C<@> within a C<\Q> sequence. -An unescaped C<$> or C<@> interpolates the corresponding variable, -while escaping will cause the literal string C<\$> to be inserted. -You'll need to write something like C<m/\Quser\E\@\Qhost/>. + "abc\Qfoo\tbar$s\Exyz" + +is equivalent to + + "abc" . quotemeta("foo\tbar$s") . "xyz" + +For the pattern of regex operators (C<qr//>, C<m//> and C<s///>), +the quoting from C<\Q> is applied after interpolation is processed, +but before escapes are processed. This allows the pattern to match +literally (except for C<$> and C<@>). For example, the following matches: + + '\s\t' =~ /\Q\s\t/ + +Because C<$> or C<@> trigger interpolation, you'll need to use something +like C</\Quser\E\@\Qhost/> to match them literally. Patterns are subject to an additional level of interpretation as a regular expression. This is done as a second pass, after variables are @@ -1112,14 +1295,14 @@ matching and related activities. =over 8 -=item qr/STRING/msixpo +=item qr/STRING/msixpodual X<qr> X</i> X</m> X</o> X</s> X</x> X</p> This operator quotes (and possibly compiles) its I<STRING> as a regular expression. I<STRING> is interpolated the same way as I<PATTERN> in C<m/PATTERN/>. If "'" is used as the delimiter, no interpolation is done. Returns a Perl value which may be used instead of the -corresponding C</STRING/msixpo> expression. The returned value is a +corresponding C</STRING/msixpodual> expression. The returned value is a normalized version of the original pattern. It magically differs from a string containing the same characters: C<ref(qr/x/)> returns "Regexp", even though dereferencing the result returns undef. @@ -1141,7 +1324,7 @@ The result may be used as a subpattern in a match: $string =~ $re; # or used standalone $string =~ /$re/; # or this way -Since Perl may compile the pattern at the moment of execution of qr() +Since Perl may compile the pattern at the moment of execution of the qr() operator, using qr() may have speed advantages in some situations, notably if the result of qr() is used standalone: @@ -1163,7 +1346,7 @@ time a match C</$pat/> is attempted. (Perl has many other internal optimizations, but none would be triggered in the above example if we did not use qr() operator.) -Options are: +Options (specified by the following modifiers) are: m Treat string as multiple lines. s Treat string as single line. (Make . match a newline) @@ -1172,62 +1355,92 @@ Options are: p When matching preserve a copy of the matched string so that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined. o Compile pattern only once. + l Use the locale + u Use Unicode rules + a Use ASCII for \d, \s, \w; specifying two a's further restricts + /i matching so that no ASCII character will match a non-ASCII + one + d Use Unicode or native charset, as in 5.12 and earlier If a precompiled pattern is embedded in a larger pattern then the effect -of 'msixp' will be propagated appropriately. The effect of the 'o' +of "msixpluad" will be propagated appropriately. The effect the "o" modifier has is not propagated, being restricted to those patterns explicitly using it. +The last four modifiers listed above, added in Perl 5.14, +control the character set semantics. + See L<perlre> for additional information on valid syntax for STRING, and -for a detailed look at the semantics of regular expressions. +for a detailed look at the semantics of regular expressions. In +particular, all the modifiers execpt C</o> are further explained in +L<perlre/Modifiers>. C</o> is described in the next section. -=item m/PATTERN/msixpogc +=item m/PATTERN/msixpodualgc 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> -=item /PATTERN/msixpogc +=item /PATTERN/msixpodualgc Searches a string for a pattern match, and in scalar context returns true if it succeeds, false if it fails. If no string is specified via the C<=~> or C<!~> operator, the $_ string is searched. (The string specified with C<=~> need not be an lvalue--it may be the result of an expression evaluation, but remember the C<=~> binds -rather tightly.) See also L<perlre>. See L<perllocale> for -discussion of additional considerations that apply when C<use locale> -is in effect. +rather tightly.) See also L<perlre>. -Options are as described in C<qr//>; in addition, the following match +Options are as described in C<qr//> above; in addition, the following match process modifiers are available: - g Match globally, i.e., find all occurrences. - c Do not reset search position on a failed match when /g is in effect. + g Match globally, i.e., find all occurrences. + c Do not reset search position on a failed match when /g is in effect. If "/" is the delimiter then the initial C<m> is optional. With the C<m> -you can use any pair of non-whitespace characters +you can use any pair of non-whitespace (ASCII) characters as delimiters. This is particularly useful for matching path names that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is -the delimiter, then the match-only-once rule of C<?PATTERN?> applies. +the delimiter, then a match-only-once rule applies, +described in C<m?PATTERN?> below. If "'" is the delimiter, no interpolation is performed on the PATTERN. When using a character valid in an identifier, whitespace is required after the C<m>. -PATTERN may contain variables, which will be interpolated (and the -pattern recompiled) every time the pattern search is evaluated, except +PATTERN may contain variables, which will be interpolated +every time the pattern search is evaluated, except for when the delimiter is a single quote. (Note that C<$(>, C<$)>, and C<$|> are not interpolated because they look like end-of-string tests.) -If you want such a pattern to be compiled only once, add a C</o> after -the trailing delimiter. This avoids expensive run-time recompilations, -and is useful when the value you are interpolating won't change over -the life of the script. However, mentioning C</o> constitutes a promise -that you won't change the variables in the pattern. If you change them, -Perl won't even notice. See also L<"qr/STRING/msixpo">. +Perl will not recompile the pattern unless an interpolated +variable that it contains changes. You can force Perl to skip the +test and never recompile by adding a C</o> (which stands for "once") +after the trailing delimiter. +Once upon a time, Perl would recompile regular expressions +unnecessarily, and this modifier was useful to tell it not to do so, in the +interests of speed. But now, the only reasons to use C</o> are either: + +=over + +=item 1 + +The variables are thousands of characters long and you know that they +don't change, and you need to wring out the last little bit of speed by +having Perl skip testing for that. (There is a maintenance penalty for +doing this, as mentioning C</o> constitutes a promise that you won't +change the variables in the pattern. If you change them, Perl won't +even notice.) + +=item 2 + +you want the pattern to use the initial values of the variables +regardless of whether they change or not. (But there are saner ways +of accomplishing this than using C</o>.) + +=back =item The empty pattern // If the PATTERN evaluates to the empty string, the last I<successfully> matched regular expression is used instead. In this -case, only the C<g> and C<c> flags on the empty pattern is honoured - +case, only the C<g> and C<c> flags on the empty pattern are honored; the other flags are taken from the original pattern. If no match has previously succeeded, this will (silently) act instead as a genuine empty pattern (which will always match). @@ -1253,7 +1466,9 @@ failure. Examples: - open(TTY, '/dev/tty'); + open(TTY, "+>/dev/tty") + || die "can't access /dev/tty: $!"; + <TTY> =~ /^y/i && foo(); # do foo if desired if (/Version: *([0-9.]*)/) { $version = $1; } @@ -1263,42 +1478,44 @@ Examples: # poor man's grep $arg = shift; while (<>) { - print if /$arg/o; # compile only once + print if /$arg/o; # compile only once (no longer needed!) } if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/)) This last example splits $foo into the first two words and the remainder of the line, and assigns those three fields to $F1, $F2, and -$Etc. The conditional is true if any variables were assigned, i.e., if -the pattern matched. +$Etc. The conditional is true if any variables were assigned; that is, +if the pattern matched. The C</g> modifier specifies global pattern matching--that is, -matching as many times as possible within the string. How it behaves -depends on the context. In list context, it returns a list of the +matching as many times as possible within the string. How it behaves +depends on the context. In list context, it returns a list of the substrings matched by any capturing parentheses in the regular -expression. If there are no parentheses, it returns a list of all +expression. If there are no parentheses, it returns a list of all the matched strings, as if there were parentheses around the whole pattern. In scalar context, each execution of C<m//g> finds the next match, returning true if it matches, and false if there is no further match. -The position after the last match can be read or set using the pos() -function; see L<perlfunc/pos>. A failed match normally resets the +The position after the last match can be read or set using the C<pos()> +function; see L<perlfunc/pos>. A failed match normally resets the search position to the beginning of the string, but you can avoid that -by adding the C</c> modifier (e.g. C<m//gc>). Modifying the target +by adding the C</c> modifier (e.g. C<m//gc>). Modifying the target string also resets the search position. =item \G assertion You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a -zero-width assertion that matches the exact position where the previous -C<m//g>, if any, left off. Without the C</g> modifier, the C<\G> assertion -still anchors at pos(), but the match is of course only attempted once. -Using C<\G> without C</g> on a target string that has not previously had a -C</g> match applied to it is the same as using the C<\A> assertion to match -the beginning of the string. Note also that, currently, C<\G> is only -properly supported when anchored at the very beginning of the pattern. +zero-width assertion that matches the exact position where the +previous C<m//g>, if any, left off. Without the C</g> modifier, the +C<\G> assertion still anchors at C<pos()> as it was at the start of +the operation (see L<perlfunc/pos>), but the match is of course only +attempted once. Using C<\G> without C</g> on a target string that has +not previously had a C</g> match applied to it is the same as using +the C<\A> assertion to match the beginning of the string. Note also +that, currently, C<\G> is only properly supported when anchored at the +very beginning of the pattern. Examples: @@ -1306,15 +1523,39 @@ Examples: ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g); # scalar context - $/ = ""; - while (defined($paragraph = <>)) { - while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) { + local $/ = ""; + while ($paragraph = <>) { + while ($paragraph =~ /\p{Ll}['")]*[.!?]+['")]*\s/g) { $sentences++; } } - print "$sentences\n"; + say $sentences; + +Here's another way to check for sentences in a paragraph: + + my $sentence_rx = qr{ + (?: (?<= ^ ) | (?<= \s ) ) # after start-of-string or whitespace + \p{Lu} # capital letter + .*? # a bunch of anything + (?<= \S ) # that ends in non-whitespace + (?<! \b [DMS]r ) # but isn't a common abbreviation + (?<! \b Mrs ) + (?<! \b Sra ) + (?<! \b St ) + [.?!] # followed by a sentence ender + (?= $ | \s ) # in front of end-of-string or whitespace + }sx; + local $/ = ""; + while (my $paragraph = <>) { + say "NEW PARAGRAPH"; + my $count = 0; + while ($paragraph =~ /($sentence_rx)/g) { + printf "\tgot sentence %d: <%s>\n", ++$count, $1; + } + } + +Here's how to use C<m//gc> with C<\G>: - # using m//gc with \G $_ = "ppooqppqq"; while ($i++ < 2) { print "1: '"; @@ -1339,8 +1580,8 @@ The last example should print: Notice that the final match matched C<q> instead of C<p>, which a match without the C<\G> anchor would have done. Also note that the final match did not update C<pos>. C<pos> is only updated on a C</g> match. If the -final match did indeed match C<p>, it's a good bet that you're running an -older (pre-5.6.0) Perl. +final match did indeed match C<p>, it's a good bet that you're running a +very old (pre-5.6.0) version of Perl. A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can combine several regexps like this to process a string part-by-part, @@ -1348,60 +1589,79 @@ doing different actions depending on which regexp matched. Each regexp tries to match where the previous one leaves off. $_ = <<'EOL'; - $url = URI::URL->new( "http://example.com/" ); die if $url eq "xXx"; + $url = URI::URL->new( "http://example.com/" ); die if $url eq "xXx"; EOL - LOOP: - { - print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc; - print(" lowercase"), redo LOOP if /\G[a-z]+\b[,.;]?\s*/gc; - print(" UPPERCASE"), redo LOOP if /\G[A-Z]+\b[,.;]?\s*/gc; - print(" Capitalized"), redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/gc; - print(" MiXeD"), redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/gc; - print(" alphanumeric"), redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/gc; - print(" line-noise"), redo LOOP if /\G[^A-Za-z0-9]+/gc; - print ". That's all!\n"; - } + + LOOP: { + print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc; + print(" lowercase"), redo LOOP if /\G\p{Ll}+\b[,.;]?\s*/gc; + print(" UPPERCASE"), redo LOOP if /\G\p{Lu}+\b[,.;]?\s*/gc; + print(" Capitalized"), redo LOOP if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc; + print(" MiXeD"), redo LOOP if /\G\pL+\b[,.;]?\s*/gc; + print(" alphanumeric"), redo LOOP if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc; + print(" line-noise"), redo LOOP if /\G\W+/gc; + print ". That's all!\n"; + } Here is the output (split into several lines): - line-noise lowercase line-noise lowercase UPPERCASE line-noise - UPPERCASE line-noise lowercase line-noise lowercase line-noise - lowercase lowercase line-noise lowercase lowercase line-noise - MiXeD line-noise. That's all! + line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE + line-noise lowercase line-noise lowercase line-noise lowercase + lowercase line-noise lowercase lowercase line-noise lowercase + lowercase line-noise MiXeD line-noise. That's all! -=item ?PATTERN? -X<?> +=item m?PATTERN?msixpodualgc +X<?> X<operator, match-once> -This is just like the C</pattern/> search, except that it matches only -once between calls to the reset() operator. This is a useful +=item ?PATTERN?msixpodualgc + +This is just like the C<m/PATTERN/> search, except that it matches +only once between calls to the reset() operator. This is a useful optimization when you want to see only the first occurrence of -something in each file of a set of files, for instance. Only C<??> +something in each file of a set of files, for instance. Only C<m??> patterns local to the current package are reset. while (<>) { - if (?^$?) { + if (m?^$?) { # blank line between header and body } } continue { - reset if eof; # clear ?? status for next file + reset if eof; # clear m?? status for next file } -This usage is vaguely deprecated, which means it just might possibly -be removed in some distant future version of Perl, perhaps somewhere -around the year 2168. +Another example switched the first "latin1" encoding it finds +to "utf8" in a pod file: + + s//utf8/ if m? ^ =encoding \h+ \K latin1 ?x; + +The match-once behavior is controlled by the match delimiter being +C<?>; with any other delimiter this is the normal C<m//> operator. + +For historical reasons, the leading C<m> in C<m?PATTERN?> is optional, +but the resulting C<?PATTERN?> syntax is deprecated, will warn on +usage and might be removed from a future stable release of Perl (without +further notice!). -=item s/PATTERN/REPLACEMENT/msixpogce +=item s/PATTERN/REPLACEMENT/msixpodualgcer 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> +X<regexp, substitute> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e> X</r> Searches a string for a pattern, and if found, replaces that pattern with the replacement text and returns the number of substitutions made. Otherwise it returns false (specifically, the empty string). +If the C</r> (non-destructive) option is used then it runs the +substitution on a copy of the string and instead of returning the +number of substitutions, it returns the copy whether or not a +substitution occurred. The original string is never changed when +C</r> is used. The copy will always be a plain string, even if the +input is an object or a tied variable. + If no string is specified via the C<=~> or C<!~> operator, the C<$_> -variable is searched and modified. (The string specified with C<=~> must -be scalar variable, an array element, a hash element, or an assignment -to one of those, i.e., an lvalue.) +variable is searched and modified. Unless the C</r> option is used, +the string specified must be a scalar variable, an array element, a +hash element, or an assignment to one of those; that is, some sort of +scalar lvalue. If the delimiter chosen is a single quote, no interpolation is done on either the PATTERN or the REPLACEMENT. Otherwise, if the @@ -1411,14 +1671,13 @@ at run-time. If you want the pattern compiled only once the first time the variable is interpolated, use the C</o> option. If the pattern evaluates to the empty string, the last successfully executed regular expression is used instead. See L<perlre> for further explanation on these. -See L<perllocale> for discussion of additional considerations that apply -when C<use locale> is in effect. Options are as with m// with the addition of the following replacement specific options: e Evaluate the right side as an expression. - ee Evaluate the right side as a string then eval the result + ee Evaluate the right side as a string then eval the result. + r Return substitution and leave the original string untouched. Any non-whitespace delimiter may replace the slashes. Add space after the C<s> when using a character allowed in identifiers. If single quotes @@ -1442,6 +1701,11 @@ Examples: s/Login: $foo/Login: $bar/; # run-time pattern ($foo = $bar) =~ s/this/that/; # copy first, then change + ($foo = "$bar") =~ s/this/that/; # convert to string, copy, then change + $foo = $bar =~ s/this/that/r; # Same as above using /r + $foo = $bar =~ s/this/that/r + =~ s/that/the other/r; # Chained substitutes using /r + @foo = map { s/this/that/r } @bar # /r is very useful in maps $count = ($paragraph =~ s/Mister\b/Mr./g); # get change-count @@ -1454,6 +1718,10 @@ Examples: s/%(.)/$percent{$1} || $&/ge; # expr now, so /e s/^=(\w+)/pod($1)/ge; # use function call + $_ = 'abc123xyz'; + $a = s/abc/def/r; # $a is 'def123xyz' and + # $_ remains 'abc123xyz'. + # expand variables in $_, but dynamics only, using # symbolic dereferencing s/\$(\w+)/${$1}/g; @@ -1461,6 +1729,9 @@ Examples: # Add one to the value of any numbers in the string s/(\d+)/1 + $1/eg; + # Titlecase words in the last 30 characters only + substr($str, -30) =~ s/\b(\p{Alpha}+)\b/\u\L$1/g; + # This will expand any embedded scalar variable # (including lexicals) in $_ : First $1 is interpolated # to the variable name, and then evaluated @@ -1495,6 +1766,14 @@ to occur that you might want. Here are two common cases: # expand tabs to 8-column spacing 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e; +C<s///le> is treated as a substitution followed by the C<le> operator, not +the C</le> flags. This may change in a future version of Perl. It +produces a warning if warnings are enabled. To disambiguate, use a space +or change the order of the flags: + + s/foo/bar/ le 5; # "le" infix operator + s/foo/bar/el; # "e" and "l" flags + =back =head2 Quote-Like Operators @@ -1570,11 +1849,11 @@ when the program is done: The STDIN filehandle used by the command is inherited from Perl's STDIN. For example: - open BLAM, "blam" || die "Can't open: $!"; - open STDIN, "<&BLAM"; - print `sort`; + open(SPLAT, "stuff") || die "can't open stuff: $!"; + open(STDIN, "<&SPLAT") || die "can't dupe SPLAT: $!"; + print STDOUT `sort`; -will print the sorted contents of the file "blam". +will print the sorted contents of the file named F<"stuff">. Using single-quote as a delimiter protects the command from Perl's double-quote interpolation, passing it on to the shell instead: @@ -1625,7 +1904,7 @@ Evaluates to a list of the words extracted out of STRING, using embedded whitespace as the word delimiters. It can be understood as being roughly equivalent to: - split(' ', q/STRING/); + split(" ", q/STRING/); the differences being that it generates a real list at compile time, and in scalar context it returns the last element in the list. So @@ -1635,7 +1914,7 @@ this expression: is semantically equivalent to the list: - 'foo', 'bar', 'baz' + "foo", "bar", "baz" Some frequently seen examples: @@ -1647,31 +1926,41 @@ put comments into a multi-line C<qw>-string. For this reason, the C<use warnings> pragma and the B<-w> switch (that is, the C<$^W> variable) produces warnings if the STRING contains the "," or the "#" character. - -=item tr/SEARCHLIST/REPLACEMENTLIST/cds +=item tr/SEARCHLIST/REPLACEMENTLIST/cdsr X<tr> X<y> X<transliterate> X</c> X</d> X</s> -=item y/SEARCHLIST/REPLACEMENTLIST/cds +=item y/SEARCHLIST/REPLACEMENTLIST/cdsr Transliterates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced or deleted. If no string is -specified via the =~ or !~ operator, the $_ string is transliterated. (The -string specified with =~ must be a scalar variable, an array element, a -hash element, or an assignment to one of those, i.e., an lvalue.) +specified via the C<=~> or C<!~> operator, the $_ string is transliterated. + +If the C</r> (non-destructive) option is present, a new copy of the string +is made and its characters transliterated, and this copy is returned no +matter whether it was modified or not: the original string is always +left unchanged. The new copy is always a plain string, even if the input +string is an object or a tied variable. + +Unless the C</r> option is used, the string specified with C<=~> must be a +scalar variable, an array element, a hash element, or an assignment to one +of those; in other words, an lvalue. A character range may be specified with a hyphen, so C<tr/A-J/0-9/> does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>. For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has -its own pair of quotes, which may or may not be bracketing quotes, -e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>. - -Note that C<tr> does B<not> do regular expression character classes -such as C<\d> or C<[:lower:]>. The C<tr> operator is not equivalent to -the tr(1) utility. If you want to map strings between lower/upper -cases, see L<perlfunc/lc> and L<perlfunc/uc>, and in general consider -using the C<s> operator if you need regular expressions. +its own pair of quotes, which may or may not be bracketing quotes; +for example, C<tr[aeiouy][yuoiea]> or C<tr(+\-*/)/ABCD/>. + +Note that C<tr> does B<not> do regular expression character classes such as +C<\d> or C<\pL>. The C<tr> operator is not equivalent to the tr(1) +utility. If you want to map strings between lower/upper cases, see +L<perlfunc/lc> and L<perlfunc/uc>, and in general consider using the C<s> +operator if you need regular expressions. The C<\U>, C<\u>, C<\L>, and +C<\l> string-interpolation escapes on the right side of a substitution +operator will perform correct case-mappings, but C<tr[a-z][A-Z]> will not +(except sometimes on legacy 7-bit data). Note also that the whole range idea is rather unportable between character sets--and even within character sets they may cause results @@ -1685,6 +1974,8 @@ Options: c Complement the SEARCHLIST. d Delete found but unreplaced characters. s Squash duplicate replaced characters. + r Return the modified string and leave the original string + untouched. If the C</c> modifier is specified, the SEARCHLIST character set is complemented. If the C</d> modifier is specified, any characters @@ -1704,7 +1995,7 @@ squashing character sequences in a class. Examples: - $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case + $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case ASCII $cnt = tr/*/*/; # count the stars in $_ @@ -1715,11 +2006,18 @@ Examples: tr/a-zA-Z//s; # bookkeeper -> bokeper ($HOST = $host) =~ tr/a-z/A-Z/; + $HOST = $host =~ tr/a-z/A-Z/r; # same thing + + $HOST = $host =~ tr/a-z/A-Z/r # chained with s///r + =~ s/:/ -p/r; tr/a-zA-Z/ /cs; # change non-alphas to single space + @stripped = map tr/a-zA-Z/ /csr, @original; + # /r with map + tr [\200-\377] - [\000-\177]; # delete 8th bit + [\000-\177]; # wickedly delete 8th bit If multiple transliterations are given for a character, only the first one is used: @@ -1781,6 +2079,17 @@ strings except that backslashes have no special meaning, with C<\\> being treated as two backslashes and not one as they would in every other quoting construct. +Just as in the shell, a backslashed bareword following the C<<< << >>> +means the same thing as a single-quoted string does: + + $cost = <<'VISTA'; # hasta la ... + That'll be $10 please, ma'am. + VISTA + + $cost = <<\VISTA; # Same thing! + That'll be $10 please, ma'am. + VISTA + This is the only form of quoting in perl where there is no need to worry about escaping content, something that code generators can and do make good use of. @@ -1857,8 +2166,8 @@ If the terminating identifier is on the last line of the program, you must be sure there is a newline after it; otherwise, Perl will give the warning B<Can't find string terminator "END" anywhere before EOF...>. -Additionally, the quoting rules for the end of string identifier are not -related to Perl's quoting rules. C<q()>, C<qq()>, and the like are not +Additionally, quoting rules for the end-of-string identifier are +unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the like are not supported in place of C<''> and C<"">, and the only interpolation is for backslashing the quoting character: @@ -1941,12 +2250,12 @@ C<tr///>), the search is repeated once more. If the first delimiter is not an opening punctuation, three delimiters must be same such as C<s!!!> and C<tr)))>, in which case the second delimiter terminates the left part and starts the right part at once. -If the left part is delimited by bracketing punctuations (that is C<()>, +If the left part is delimited by bracketing punctuation (that is C<()>, C<[]>, C<{}>, or C<< <> >>), the right part needs another pair of -delimiters such as C<s(){}> and C<tr[]//>. In these cases, whitespaces +delimiters such as C<s(){}> and C<tr[]//>. In these cases, whitespace and comments are allowed between both parts, though the comment must follow -at least one whitespace; otherwise a character expected as the start of -the comment may be regarded as the starting delimiter of the right part. +at least one whitespace character; otherwise a character expected as the +start of the comment may be regarded as the starting delimiter of the right part. During this search no attention is paid to the semantics of the construct. Thus: @@ -2483,17 +2792,17 @@ floating point. But by saying use integer; -you may tell the compiler that it's okay to use integer operations -(if it feels like it) from here to the end of the enclosing BLOCK. -An inner BLOCK may countermand this by saying +you may tell the compiler to use integer operations +(see L<integer> for a detailed explanation) from here to the end of +the enclosing BLOCK. An inner BLOCK may countermand this by saying no integer; which lasts until the end of that BLOCK. Note that this doesn't -mean everything is only an integer, merely that Perl may use integer -operations if it is so inclined. For example, even under C<use -integer>, if you take the C<sqrt(2)>, you'll still get C<1.4142135623731> -or so. +mean everything is an integer, merely that Perl will use integer +operations for arithmetic, comparison, and bitwise operators. For +example, even under C<use integer>, if you take the C<sqrt(2)>, you'll +still get C<1.4142135623731> or so. Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<", and ">>") always produce integral results. (But see also @@ -2550,36 +2859,47 @@ need yourself. =head2 Bigger Numbers X<number, arbitrary precision> -The standard Math::BigInt and Math::BigFloat modules provide +The standard C<Math::BigInt>, C<Math::BigRat>, and C<Math::BigFloat> modules, +along with the C<bigint>, C<bigrat>, and C<bitfloat> pragmas, provide variable-precision arithmetic and overloaded operators, although they're currently pretty slow. At the cost of some space and considerable speed, they avoid the normal pitfalls associated with limited-precision representations. - use Math::BigInt; - $x = Math::BigInt->new('123456789123456789'); - print $x * $x; + use 5.010; + use bigint; # easy interface to Math::BigInt + $x = 123456789123456789; + say $x * $x; + +15241578780673678515622620750190521 + +Or with rationals: - # prints +15241578780673678515622620750190521 + use 5.010; + use bigrat; + $a = 3/22; + $b = 4/6; + say "a/b is ", $a/$b; + say "a*b is ", $a*$b; + a/b is 9/44 + a*b is 1/11 -There are several modules that let you calculate with (bound only by -memory and cpu-time) unlimited or fixed precision. There are also -some non-standard modules that provide faster implementations via -external C libraries. +Several modules let you calculate with (bound only by memory and CPU time) +unlimited or fixed precision. There are also some non-standard modules that +provide faster implementations via external C libraries. Here is a short, but incomplete summary: - Math::Fraction big, unlimited fractions like 9973 / 12967 - Math::String treat string sequences like numbers - Math::FixedPrecision calculate with a fixed precision - Math::Currency for currency calculations - Bit::Vector manipulate bit vectors fast (uses C) - Math::BigIntFast Bit::Vector wrapper for big numbers - Math::Pari provides access to the Pari C library - Math::BigInteger uses an external C library - Math::Cephes uses external Cephes C library (no big numbers) - Math::Cephes::Fraction fractions via the Cephes library - Math::GMP another one using an external C library + Math::Fraction big, unlimited fractions like 9973 / 12967 + Math::String treat string sequences like numbers + Math::FixedPrecision calculate with a fixed precision + Math::Currency for currency calculations + Bit::Vector manipulate bit vectors fast (uses C) + Math::BigIntFast Bit::Vector wrapper for big numbers + Math::Pari provides access to the Pari C library + Math::BigInteger uses an external C library + Math::Cephes uses external Cephes C library (no big numbers) + Math::Cephes::Fraction fractions via the Cephes library + Math::GMP another one using an external C library Choose wisely. diff --git a/Master/tlpkg/tlperl/lib/pods/perlopenbsd.pod b/Master/tlpkg/tlperl/lib/pods/perlopenbsd.pod index b1d5eea14f4..0c9b3c4f365 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlopenbsd.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlopenbsd.pod @@ -14,7 +14,7 @@ version 5 (hereafter just Perl) is compiled and/or runs. =head2 OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads When Perl is configured to use ithreads, it will use re-entrant library calls -in preference to non-re-entrant versions. There is an incompatability in +in preference to non-re-entrant versions. There is an incompatibility in OpenBSD's C<getprotobyname_r> and C<getservbyname_r> function in versions 3.7 and later that will cause a SEGV when called without doing a C<bzero> on their return structs prior to calling these functions. Current Perl's diff --git a/Master/tlpkg/tlperl/lib/pods/perlopentut.pod b/Master/tlpkg/tlperl/lib/pods/perlopentut.pod index ea4b307b459..4bb43bffd76 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlopentut.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlopentut.pod @@ -55,7 +55,7 @@ If you prefer the low-punctuation version, you could write that this way: open RESULTS,"> runstats" or die "can't open runstats: $!"; open LOG, ">> logfile " or die "can't open logfile: $!"; -A few things to notice. First, the leading less-than is optional. +A few things to notice. First, the leading C<< < >> is optional. If omitted, Perl assumes that you want to open the file for reading. Note also that the first example uses the C<||> logical operator, and the @@ -117,13 +117,30 @@ like C<my $infile>, there's no clash and no need to worry about future conflicts. Another convenient behavior is that an indirect filehandle automatically -closes when it goes out of scope or when you undefine it: +closes when there are no more references to it: sub firstline { open( my $in, shift ) && return scalar <$in>; # no close() required } +Indirect filehandles also make it easy to pass filehandles to and return +filehandles from subroutines: + + for my $file ( qw(this.conf that.conf) ) { + my $fin = open_or_throw('<', $file); + process_conf( $fin ); + # no close() needed + } + + use Carp; + sub open_or_throw { + my ($mode, $filename) = @_; + open my $h, $mode, $filename + or croak "Could not open '$filename': $!"; + return $h; + } + =head2 Pipe Opens In C, when you want to open a file using the standard I/O library, diff --git a/Master/tlpkg/tlperl/lib/pods/perlos2.pod b/Master/tlpkg/tlperl/lib/pods/perlos2.pod index 1d4083f8d5f..e7d6cca342f 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlos2.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlos2.pod @@ -487,7 +487,7 @@ DPMI is required for RSX. The whole idea of the "standard C API to start applications" is that the forms C<foo> and C<"foo"> of program arguments are completely -interchangable. F<find> breaks this paradigm; +interchangeable. F<find> breaks this paradigm; find "pattern" file find pattern file @@ -618,7 +618,7 @@ C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">. =item Additional Perl modules - unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.12.3/ + unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.14.2/ Same remark as above applies. Additionally, if this directory is not one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you @@ -1499,7 +1499,7 @@ Here is the sample C file: { main_t f; handler_t h; - + me = argv[0]; /**/ handle = load_perl_dll(PERL_DLL_BASENAME); @@ -1649,7 +1649,7 @@ leaves drive as it is. =item C<Cwd::change_drive(name)> -chanes the "current" drive. +changes the "current" drive. =item C<Cwd::sys_is_absolute(name)> @@ -1896,7 +1896,7 @@ _DLLInitTerm() (e.g., F<TCP32IP>). This means that even if you do not I<call> any function in the DLL, just the act of loading this DLL will reset your flags. What is worse, the same compiler was used to compile some HOOK DLLs. Given that HOOK dlls are executed in the context of I<all> the applications -in the system, this means a complete unpredictablity of floating point +in the system, this means a complete unpredictability of floating point flags on systems using such HOOK DLLs. E.g., F<GAMESRVR.DLL> of B<DIVE> origin changes the floating point flags on each write to the TTY of a VIO (windowed text-mode) applications. @@ -2025,7 +2025,7 @@ WM_QUIT, and which did not process the received WM_QUIT message, the shutdown will be automatically cancelled. Do not call C<perl_hmq_GET(1)> unless you are going to process messages on an orderly basis. -=item * Treating errors reported by OS/2 API +=item Treating errors reported by OS/2 API There are two principal conventions (it is useful to call them C<Dos*> and C<Win*> - though this part of the function signature is not always @@ -2102,7 +2102,7 @@ Sets C<Perl_rc> to C<rc>, and sets $^E to the corresponding value. =back -=item * Loading DLLs and ordinals in DLLs +=item Loading DLLs and ordinals in DLLs Some DLLs are only present in some versions of OS/2, or in some configurations of OS/2. Some exported entry points are present only diff --git a/Master/tlpkg/tlperl/lib/pods/perlos390.pod b/Master/tlpkg/tlperl/lib/pods/perlos390.pod index 4229e2b317e..93459346c37 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlos390.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlos390.pod @@ -260,7 +260,7 @@ from an account with write access to the directory entry for /tmp. Out of Memory! -Recent perl test suite is quite memory hunrgy. In addition to the comments +Recent perl test suite is quite memory hungry. In addition to the comments above on memory limitations it is also worth checking for _CEE_RUNOPTS in your environment. Perl now has (in miniperlmain.c) a C #pragma to set CEE run options, but the environment variable wins. diff --git a/Master/tlpkg/tlperl/lib/pods/perlos400.pod b/Master/tlpkg/tlperl/lib/pods/perlos400.pod index cd789166955..0dcee2e4290 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlos400.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlos400.pod @@ -14,7 +14,7 @@ compiled and/or runs. By far the easiest way to build Perl for OS/400 is to use the PASE (Portable Application Solutions Environment), for more information see -http://www.iseries.ibm.com/developer/factory/pase/index.html +L<http://www.iseries.ibm.com/developer/factory/pase/index.html> This environment allows one to use AIX APIs while programming, and it provides a runtime that allows AIX binaries to execute directly on the PowerPC iSeries. @@ -105,7 +105,7 @@ There exists a port of Perl to the ILE environment. This port, however, is based quite an old release of Perl, Perl 5.00502 (August 1998). (As of July 2002 the latest release of Perl is 5.8.0, and even 5.6.1 has been out since April 2001.) If you need to run Perl on ILE, though, -you may need this older port: http://www.cpan.org/ports/#os400 +you may need this older port: L<http://www.cpan.org/ports/#os400> Note that any Perl release later than 5.00502 has not been ported to ILE. If you need to use Perl in the ILE environment, you may want to consider diff --git a/Master/tlpkg/tlperl/lib/pods/perlperf.pod b/Master/tlpkg/tlperl/lib/pods/perlperf.pod index a934271088b..cac6eee6655 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlperf.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlperf.pod @@ -567,7 +567,7 @@ 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 +See also the L<DBIx::Profile> which will profile database queries running under the C<DBIx::*> namespace. =head2 Devel::NYTProf @@ -1137,7 +1137,7 @@ deserve further attention. Apache::DProf Apache::SmallProf Benchmark - DBIx::Profiler + DBIx::Profile Devel::AutoProfiler Devel::DProf Devel::DProfLB diff --git a/Master/tlpkg/tlperl/lib/pods/perlpod.pod b/Master/tlpkg/tlperl/lib/pods/perlpod.pod index 90bc5b1d8f8..068afe4177d 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlpod.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlpod.pod @@ -474,7 +474,7 @@ C<EE<lt>verbarE<gt>> -- a literal | (I<ver>tical I<bar>) =item * -C<EE<lt>solE<gt>> = a literal / (I<sol>idus) +C<EE<lt>solE<gt>> -- a literal / (I<sol>idus) The above four are optional except in other formatting codes, notably C<LE<lt>...E<gt>>, and when preceded by a diff --git a/Master/tlpkg/tlperl/lib/pods/perlpodspec.pod b/Master/tlpkg/tlperl/lib/pods/perlpodspec.pod index 0bf84e09104..dbe05391dff 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlpodspec.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlpodspec.pod @@ -1,3 +1,4 @@ +=encoding utf8 =head1 NAME diff --git a/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod b/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod new file mode 100644 index 00000000000..6c4cfa04afc --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perlpodstyle.pod @@ -0,0 +1,295 @@ +=head1 NAME + +perlpodstyle - Perl POD style guide + +=head1 DESCRIPTION + +These are general guidelines for how to write POD documentation for Perl +scripts and modules, based on general guidelines for writing good UNIX man +pages. All of these guidelines are, of course, optional, but following +them will make your documentation more consistent with other documentation +on the system. + +The name of the program being documented is conventionally written in bold +(using BE<lt>E<gt>) wherever it occurs, as are all program options. +Arguments should be written in italics (IE<lt>E<gt>). Function names are +traditionally written in italics; if you write a function as function(), +Pod::Man will take care of this for you. Literal code or commands should +be in CE<lt>E<gt>. References to other man pages should be in the form +C<manpage(section)> or C<LE<lt>manpage(section)E<gt>>, and Pod::Man will +automatically format those appropriately. The second form, with +LE<lt>E<gt>, is used to request that a POD formatter make a link to the +man page if possible. As an exception, one normally omits the section +when referring to module documentation since it's not clear what section +module documentation will be in; use C<LE<lt>Module::NameE<gt>> for module +references instead. + +References to other programs or functions are normally in the form of man +page references so that cross-referencing tools can provide the user with +links and the like. It's possible to overdo this, though, so be careful not +to clutter your documentation with too much markup. References to other +programs that are not given as man page references should be enclosed in +BE<lt>E<gt>. + +The major headers should be set out using a C<=head1> directive, and are +historically written in the rather startling ALL UPPER CASE format; this +is not mandatory, but it's strongly recommended so that sections have +consistent naming across different software packages. Minor headers may +be included using C<=head2>, and are typically in mixed case. + +The standard sections of a manual page are: + +=over 4 + +=item NAME + +Mandatory section; should be a comma-separated list of programs or +functions documented by this POD page, such as: + + foo, bar - programs to do something + +Manual page indexers are often extremely picky about the format of this +section, so don't put anything in it except this line. Every program or +function documented by this POD page should be listed, separated by a +comma and a space. For a Perl module, just give the module name. A +single dash, and only a single dash, should separate the list of programs +or functions from the description. Do not use any markup such as +CE<lt>E<gt> or BE<lt>E<gt> anywhere in this line. Functions should not be +qualified with C<()> or the like. The description should ideally fit on a +single line, even if a man program replaces the dash with a few tabs. + +=item SYNOPSIS + +A short usage summary for programs and functions. This section is +mandatory for section 3 pages. For Perl module documentation, it's +usually convenient to have the contents of this section be a verbatim +block showing some (brief) examples of typical ways the module is used. + +=item DESCRIPTION + +Extended description and discussion of the program or functions, or the +body of the documentation for man pages that document something else. If +particularly long, it's a good idea to break this up into subsections +C<=head2> directives like: + + =head2 Normal Usage + + =head2 Advanced Features + + =head2 Writing Configuration Files + +or whatever is appropriate for your documentation. + +For a module, this is generally where the documentation of the interfaces +provided by the module goes, usually in the form of a list with an +C<=item> for each interface. Depending on how many interfaces there are, +you may want to put that documentation in separate METHODS, FUNCTIONS, +CLASS METHODS, or INSTANCE METHODS sections instead and save the +DESCRIPTION section for an overview. + +=item OPTIONS + +Detailed description of each of the command-line options taken by the +program. This should be separate from the description for the use of +parsers like L<Pod::Usage>. This is normally presented as a list, with +each option as a separate C<=item>. The specific option string should be +enclosed in BE<lt>E<gt>. Any values that the option takes should be +enclosed in IE<lt>E<gt>. For example, the section for the option +B<--section>=I<manext> would be introduced with: + + =item B<--section>=I<manext> + +Synonymous options (like both the short and long forms) are separated by a +comma and a space on the same C<=item> line, or optionally listed as their +own item with a reference to the canonical name. For example, since +B<--section> can also be written as B<-s>, the above would be: + + =item B<-s> I<manext>, B<--section>=I<manext> + +Writing the short option first is recommended because it's easier to read. +The long option is long enough to draw the eye to it anyway and the short +option can otherwise get lost in visual noise. + +=item RETURN VALUE + +What the program or function returns, if successful. This section can be +omitted for programs whose precise exit codes aren't important, provided +they return 0 on success and non-zero on failure as is standard. It +should always be present for functions. For modules, it may be useful to +summarize return values from the module interface here, or it may be more +useful to discuss return values separately in the documentation of each +function or method the module provides. + +=item ERRORS + +Exceptions, error return codes, exit statuses, and errno settings. +Typically used for function or module documentation; program documentation +uses DIAGNOSTICS instead. The general rule of thumb is that errors +printed to C<STDOUT> or C<STDERR> and intended for the end user are +documented in DIAGNOSTICS while errors passed internal to the calling +program and intended for other programmers are documented in ERRORS. When +documenting a function that sets errno, a full list of the possible errno +values should be given here. + +=item DIAGNOSTICS + +All possible messages the program can print out and what they mean. You +may wish to follow the same documentation style as the Perl documentation; +see perldiag(1) for more details (and look at the POD source as well). + +If applicable, please include details on what the user should do to +correct the error; documenting an error as indicating "the input buffer is +too small" without telling the user how to increase the size of the input +buffer (or at least telling them that it isn't possible) aren't very +useful. + +=item EXAMPLES + +Give some example uses of the program or function. Don't skimp; users +often find this the most useful part of the documentation. The examples +are generally given as verbatim paragraphs. + +Don't just present an example without explaining what it does. Adding a +short paragraph saying what the example will do can increase the value of +the example immensely. + +=item ENVIRONMENT + +Environment variables that the program cares about, normally presented as +a list using C<=over>, C<=item>, and C<=back>. For example: + + =over 6 + + =item HOME + + Used to determine the user's home directory. F<.foorc> in this + directory is read for configuration details, if it exists. + + =back + +Since environment variables are normally in all uppercase, no additional +special formatting is generally needed; they're glaring enough as it is. + +=item FILES + +All files used by the program or function, normally presented as a list, +and what it uses them for. File names should be enclosed in FE<lt>E<gt>. +It's particularly important to document files that will be potentially +modified. + +=item CAVEATS + +Things to take special care with, sometimes called WARNINGS. + +=item BUGS + +Things that are broken or just don't work quite right. + +=item RESTRICTIONS + +Bugs you don't plan to fix. :-) + +=item NOTES + +Miscellaneous commentary. + +=item AUTHOR + +Who wrote it (use AUTHORS for multiple people). It's a good idea to +include your current e-mail address (or some e-mail address to which bug +reports should be sent) or some other contact information so that users +have a way of contacting you. Remember that program documentation tends +to roam the wild for far longer than you expect and pick a contact method +that's likely to last. + +=item HISTORY + +Programs derived from other sources sometimes have this. Some people keep +a modification log here, but that usually gets long and is normally better +maintained in a separate file. + +=item COPYRIGHT AND LICENSE + +For copyright + + Copyright YEAR(s) YOUR NAME(s) + +(No, (C) is not needed. No, "all rights reserved" is not needed.) + +For licensing the easiest way is to use the same licensing as Perl itself: + + This library is free software; you may redistribute it and/or modify + it under the same terms as Perl itself. + +This makes it easy for people to use your module with Perl. Note that +this licensing example is neither an endorsement or a requirement, you are +of course free to choose any licensing. + +=item SEE ALSO + +Other man pages to check out, like man(1), man(7), makewhatis(8), or +catman(8). Normally a simple list of man pages separated by commas, or a +paragraph giving the name of a reference work. Man page references, if +they use the standard C<name(section)> form, don't have to be enclosed in +LE<lt>E<gt> (although it's recommended), but other things in this section +probably should be when appropriate. + +If the package has a mailing list, include a URL or subscription +instructions here. + +If the package has a web site, include a URL here. + +=back + +Documentation of object-oriented libraries or modules may want to use +CONSTRUCTORS and METHODS sections, or CLASS METHODS and INSTANCE METHODS +sections, for detailed documentation of the parts of the library and save +the DESCRIPTION section for an overview. Large modules with a function +interface may want to use FUNCTIONS for similar reasons. Some people use +OVERVIEW to summarize the description if it's quite long. + +Section ordering varies, although NAME must always be the first section +(you'll break some man page systems otherwise), and NAME, SYNOPSIS, +DESCRIPTION, and OPTIONS generally always occur first and in that order if +present. In general, SEE ALSO, AUTHOR, and similar material should be +left for last. Some systems also move WARNINGS and NOTES to last. The +order given above should be reasonable for most purposes. + +Some systems use CONFORMING TO to note conformance to relevant standards +and MT-LEVEL to note safeness for use in threaded programs or signal +handlers. These headings are primarily useful when documenting parts of a +C library. + +Finally, as a general note, try not to use an excessive amount of markup. +As documented here and in L<Pod::Man>, you can safely leave Perl +variables, function names, man page references, and the like unadorned by +markup and the POD translators will figure it out for you. This makes it +much easier to later edit the documentation. Note that many existing +translators will do the wrong thing with e-mail addresses when wrapped in +LE<lt>E<gt>, so don't do that. + +=head1 SEE ALSO + +For additional information that may be more accurate for your specific +system, see either L<man(5)> or L<man(7)> depending on your system manual +section numbering conventions. + +This documentation is maintained as part of the podlators distribution. +The current version is always available from its web site at +<http://www.eyrie.org/~eagle/software/podlators/>. + +=head1 AUTHOR + +Russ Allbery <rra@stanford.edu>, with large portions of this documentation +taken from the documentation of the original B<pod2man> implementation by +Larry Wall and Tom Christiansen. + +=head1 COPYRIGHT AND LICENSE + +Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery +<rra@stanford.edu>. + +This documentation is free software; you may redistribute it and/or modify +it under the same terms as Perl itself. + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlpolicy.pod b/Master/tlpkg/tlperl/lib/pods/perlpolicy.pod index 5b078781588..2341414cc48 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlpolicy.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlpolicy.pod @@ -1,6 +1,6 @@ =head1 NAME -perlpolicy - Various and sundry policies and commitments related to the perl core +perlpolicy - Various and sundry policies and commitments related to the Perl core =head1 DESCRIPTION @@ -20,7 +20,7 @@ As a volunteer organization, the commitments we make are heavily dependent on the goodwill and hard work of individuals who have no obligation to contribute to Perl. -That being said, we value Perl's stabilty and security and have long +That being said, we value Perl's stability and security and have long had an unwritten covenant with the broader Perl community to support and maintain releases of Perl. @@ -32,23 +32,23 @@ the Perl community should expect from Perl's developers: =item * We "officially" support the two most recent stable release -series'. As of the release of 5.14.0, we will "officially" +series. As of the release of 5.14.0, we will "officially" end support for Perl 5.10, other than providing security updates as described below. =item * To the best of our ability, we will attempt to fix critical issues -in the two most recent stable 5.x release series'. Fixes for the +in the two most recent stable 5.x release series. Fixes for the current release series take precedence over fixes for the previous release series. =item * To the best of our ability, we will provide "critical" security patches -/ releases for any major version of Perl initially released within the -past three years. We can only commit to providing these for the most -recent .y release in any 5.x.y series. +/ releases for any major version of Perl whose 5.x.0 release was within +the past three years. We can only commit to providing these for the +most recent .y release in any 5.x.y series. =item * @@ -133,7 +133,7 @@ bug as a feature, we need to treat it as such. New syntax and semantics which don't break existing language constructs and syntax have a much lower bar. They merely need to prove themselves -to be useful, elegant, well designed and well tested. +to be useful, elegant, well designed, and well tested. =head2 Terminology @@ -154,7 +154,7 @@ an experimental feature useful and want to help shape its future. =item deprecated If something in the Perl core is marked as B<deprecated>, we may remove it -from thecore in the next stable release series, though we may not. As of +from the core in the next stable release series, though we may not. As of Perl 5.12, deprecated features and modules warn the user as they're used. If you use a deprecated feature and believe that its removal from the Perl core would be a mistake, please contact the perl5-porters mailinglist and @@ -168,12 +168,12 @@ From time to time, we may mark language constructs and features which we consider to have been mistakes as B<discouraged>. Discouraged features aren't candidates for removal in the next major release series, but we may later deprecate them if they're found to stand in the way of a -significant improvement to the core. +significant improvement to the Perl core. =item removed Once a feature, construct or module has been marked as deprecated for a -stable release cycle, we may remove it from the core. Unsurprisingly, +stable release cycle, we may remove it from the Perl core. Unsurprisingly, we say we've B<removed> these things. =back @@ -198,7 +198,9 @@ acceptable. =item * -Documentation updates are acceptable. +Acceptable documentation updates are those that correct factual errors, +explain significant bugs or deficiencies in the current implementation, +or fix broken markup. =item * @@ -223,6 +225,13 @@ fix crashing or security issues (as above). =item * +Minimal patches that fix platform-specific test failures or +installation issues are acceptable. When these changes are made +to dual-life modules for which CPAN is canonical, any changes +should be coordinated with the upstream author. + +=item * + New versions of dual-life modules should NOT be imported into maint. Those belong in the next stable series. @@ -277,7 +286,7 @@ the heart of Perl itself, is a joint project on the part of all of us. From time to time, a script, module, or set of modules (hereafter referred to simply as a "module") will prove so widely useful and/or so integral to the correct functioning of Perl itself that it should be distributed with -Perl core. This should never be done without the author's explicit +the Perl core. This should never be done without the author's explicit consent, and a clear recognition on all parts that this means the module is being distributed under the same terms as Perl itself. A module author should realize that inclusion of a module into the Perl core will @@ -294,7 +303,7 @@ gives up their ownership of it. In particular: =item * -The version of the module in the core should still be considered the +The version of the module in the Perl core should still be considered the work of the original author. All patches, bug reports, and so forth should be fed back to them. Their development directions should be respected whenever possible. @@ -333,11 +342,11 @@ As a last resort, however: If the author's vision of the future of their module is sufficiently different from the vision of the pumpkin holder and perl5-porters as a whole so as to cause serious problems for Perl, the pumpkin holder may -choose to formally fork the version of the module in the core from the +choose to formally fork the version of the module in the Perl core from the one maintained by the author. This should not be done lightly and should B<always> if at all possible be done only after direct input from Larry. If this is done, it must then be made explicit in the -module as distributed with Perl core that it is a forked version and +module as distributed with the Perl core that it is a forked version and that while it is based on the original author's work, it is no longer maintained by them. This must be noted in both the documentation and in the comments in the source of the module. @@ -370,7 +379,45 @@ necessary, and certainly no more drastic measure should be used until every avenue of communication and discussion has failed. +=head1 DOCUMENTATION + +Perl's documentation is an important resource for our users. It's +incredibly important for Perl's documentation to be reasonably coherent +and to accurately reflect the current implementation. + +Just as P5P collectively maintains the codebase, we collectively +maintain the documentation. Writing a particular bit of documentation +doesn't give an author control of the future of that documentation. +At the same time, just as source code changes should match the style +of their surrounding blocks, so should documentation changes. + +Examples in documentation should be illustrative of the concept +they're explaining. Sometimes, the best way to show how a +language feature works is with a small program the reader can +run without modification. More often, examples will consist +of a snippet of code containing only the "important" bits. +The definition of "important" varies from snippet to snippet. +Sometimes it's important to declare C<use strict> and C<use warnings>, +initialize all variables and fully catch every error condition. +More often than not, though, those things obscure the lesson +the example was intended to teach. + +As Perl is developed by a global team of volunteers, our +documentation often contains spellings which look funny +to I<somebody>. Choice of American/British/Other spellings +is left as an exercise for the author of each bit of +documentation. When patching documentation, try to emulate +the documentation around you, rather than changing the existing +prose. + +In general, documentation should describe what Perl does "now" rather +than what it used to do. It's perfectly reasonable to include notes +in documentation about how behaviour has changed from previous releases, +but, with very few exceptions, documentation isn't "dual-life" -- +it doesn't need to fully describe how all old versions used to work. + + =head1 CREDITS -Social Contract about Contributed Modules originally by Russ Allbery E<lt>rra@stanford.eduE<gt> and the perl5-porters. +"Social Contract about Contributed Modules" originally by Russ Allbery E<lt>rra@stanford.eduE<gt> and the perl5-porters. diff --git a/Master/tlpkg/tlperl/lib/pods/perlport.pod b/Master/tlpkg/tlperl/lib/pods/perlport.pod index 9c81e73e445..0193dc852ca 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlport.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlport.pod @@ -480,17 +480,17 @@ file name. To convert $^X to a file pathname, taking account of the requirements of the various operating system possibilities, say: - use Config; - my $thisperl = $^X; - if ($^O ne 'VMS') - {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;} + use Config; + my $thisperl = $^X; + if ($^O ne 'VMS') + {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;} To convert $Config{perlpath} to a file pathname, say: - use Config; - my $thisperl = $Config{perlpath}; - if ($^O ne 'VMS') - {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;} + use Config; + my $thisperl = $Config{perlpath}; + if ($^O ne 'VMS') + {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;} =head2 Networking @@ -624,7 +624,7 @@ because that is OS- and implementation-specific. It is better to store a date in an unambiguous representation. The ISO 8601 standard defines YYYY-MM-DD as the date format, or YYYY-MM-DDTHH-MM-SS (that's a literal "T" separating the date from the time). -Please do use the ISO 8601 instead of making us to guess what +Please do use the ISO 8601 instead of making us guess what date 02/03/04 might be. ISO 8601 even sorts nicely as-is. A text representation (like "1987-12-18") can be easily converted into an OS-specific value using a module like Date::Parse. @@ -771,11 +771,11 @@ Also see: =item * -Mailing list: cpan-testers@perl.org +Mailing list: cpan-testers-discuss@perl.org =item * -Testing results: http://testers.cpan.org/ +Testing results: L<http://www.cpantesters.org/> =back @@ -929,13 +929,13 @@ Also see: =item * -The djgpp environment for DOS, http://www.delorie.com/djgpp/ +The djgpp environment for DOS, L<http://www.delorie.com/djgpp/> and L<perldos>. =item * The EMX environment for DOS, OS/2, etc. emx@iaehv.nl, -ftp://hobbes.nmsu.edu/pub/os2/dev/emx/ Also L<perlos2>. +L<ftp://hobbes.nmsu.edu/pub/os2/dev/emx/> Also L<perlos2>. =item * @@ -948,17 +948,17 @@ The C<Win32::*> modules in L<Win32>. =item * -The ActiveState Pages, http://www.activestate.com/ +The ActiveState Pages, L<http://www.activestate.com/> =item * The Cygwin environment for Win32; F<README.cygwin> (installed -as L<perlcygwin>), http://www.cygwin.com/ +as L<perlcygwin>), L<http://www.cygwin.com/> =item * The U/WIN environment for Win32, -http://www.research.att.com/sw/tools/uwin/ +L<http://www.research.att.com/sw/tools/uwin/> =item * @@ -1092,7 +1092,7 @@ Pumpkings and module integrators can easily see whether files with too many directory levels have snuck into the core by running the following in the top-level source directory: - $ perl -ne "$_=~s/\s+.*//; print if scalar(split /\//) > 8;" < MANIFEST + $ perl -ne "$_=~s/\s+.*//; print if scalar(split /\//) > 8;" < MANIFEST The VMS::Filespec module, which gets installed as part of the build @@ -1145,7 +1145,7 @@ Also see: =item * -F<README.vms> (installed as L<README_vms>), L<perlvms> +F<README.vms> (installed as F<README_vms>), L<perlvms> =item * @@ -1153,7 +1153,7 @@ vmsperl list, vmsperl-subscribe@perl.org =item * -vmsperl on the web, http://www.sidhe.org/vmsperl/index.html +vmsperl on the web, L<http://www.sidhe.org/vmsperl/index.html> =back @@ -1187,7 +1187,7 @@ feature known as extended names. On these releases, file names can contain up to 255 characters, are prohibited from starting with a C<-> character, and the set of prohibited characters is reduced to any character matching C<< tr/#%*<>?// >>. There are -restrictions involving spaces and apostrophies: these characters +restrictions involving spaces and apostrophes: these characters must not begin or end a name, nor can they immediately precede or follow a period. Additionally, a space must not immediately precede another space or hyphen. Specifically, the following @@ -1229,7 +1229,7 @@ Anonymous FTP site. =item * -VOS Perl on the web at http://ftp.stratus.com/pub/vos/posix/posix.html +VOS Perl on the web at L<http://ftp.stratus.com/pub/vos/posix/posix.html> =back @@ -1298,7 +1298,7 @@ The values of C<$^O> on some of these platforms includes: Some simple tricks for determining if you are running on an EBCDIC platform could include any of the following (perhaps all): - if ("\t" eq "\05") { print "EBCDIC may be spoken here!\n"; } + if ("\t" eq "\005") { print "EBCDIC may be spoken here!\n"; } if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; } @@ -1327,7 +1327,7 @@ general usage issues for all EBCDIC Perls. Send a message body of =item * AS/400 Perl information at -http://as400.rochester.ibm.com/ +L<http://as400.rochester.ibm.com/> as well as on CPAN in the F<ports/> directory. =back @@ -1470,12 +1470,12 @@ Be OS, F<README.beos> =item * HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page -http://www.bixby.org/mark/porting.html +L<http://www.bixby.org/mark/porting.html> =item * A free perl5-based PERL.NLM for Novell Netware is available in -precompiled binary and source code form from http://www.novell.com/ +precompiled binary and source code form from L<http://www.novell.com/> as well as from CPAN. =item * @@ -1618,6 +1618,8 @@ Implemented via Spawn. (VM/ESA) Does not automatically flush output handles on some platforms. (SunOS, Solaris, HP-UX) +Not supported. (Symbian OS) + =item exit Emulates Unix exit() (which considers C<exit 1> to indicate an error) by @@ -1632,17 +1634,23 @@ enabled, a generic number will be encoded in a method compatible with the C library _POSIX_EXIT macro so that it can be decoded by other programs, particularly ones written in C, like the GNV package. (VMS) +C<exit()> resets file pointers, which is a problem when called +from a child process (created by C<fork()>) in C<BEGIN>. +A workaround is to use C<POSIX::_exit>. (Solaris) + + exit unless $Config{archname} =~ /\bsolaris\b/; + require POSIX and POSIX::_exit(0); + =item fcntl Not implemented. (Win32) + Some functions available based on the version of VMS. (VMS) =item flock Not implemented (VMS, S<RISC OS>, VOS). -Available only on Windows NT (not on Windows 95). (Win32) - =item fork Not implemented. (AmigaOS, S<RISC OS>, VM/ESA, VMS) @@ -1833,7 +1841,7 @@ Available on 64 bit OpenVMS 8.2 and later. (VMS) =item localtime -localtime() has the same range as L<gmtime>, but because time zone +localtime() has the same range as L</gmtime>, but because time zone rules change its accuracy for historical and future times may degrade but usually by no more than an hour. @@ -1868,6 +1876,12 @@ Not implemented. (Win32, VMS, S<RISC OS>) Can't move directories between directories on different logical volumes. (Win32) +=item rewinddir + +Will not cause readdir() to re-read the directory stream. The entries +already read before the rewinddir() call will just be returned again +from a cache buffer. (Win32) + =item select Only implemented on sockets. (Win32, VMS) @@ -2057,7 +2071,7 @@ Not useful. (S<RISC OS>) The following platforms are known to build Perl 5.12 (as of April 2010, its release date) from the standard source code distribution available -at http://www.cpan.org/src +at L<http://www.cpan.org/src> =over @@ -2105,6 +2119,8 @@ at http://www.cpan.org/src =item FreeBSD +=item Debian GNU/kFreeBSD + =item Haiku =item Irix (6.5. What else?) @@ -2113,6 +2129,8 @@ at http://www.cpan.org/src =item Dragonfly BSD +=item QNX Neutrino RTOS (6.5.0) + =item MirOS BSD Caveats: @@ -2132,7 +2150,7 @@ Caveats: =back -=head1 EOL Platforms (Perl 5.12) +=head1 EOL Platforms (Perl 5.14) The following platforms were supported by a previous version of Perl but have been officially removed from Perl's source code @@ -2150,9 +2168,8 @@ as of 5.12: =back -The following platforms may still work as of Perl 5.12, but Perl's -developers have made an explicit decision to discontinue support for -them: +The following platforms were supported up to 5.10. They may still +have worked in 5.12, but supporting code has been removed for 5.14: =over @@ -2170,7 +2187,7 @@ them: As of July 2002 (the Perl release 5.8.0), the following platforms were able to build Perl from the standard source code distribution -available at http://www.cpan.org/src/ +available at L<http://www.cpan.org/src/> AIX BeOS @@ -2275,7 +2292,7 @@ of any trouble. Unisys Dynix The following platforms have their own source code distributions and -binaries available via http://www.cpan.org/ports/ +binaries available via L<http://www.cpan.org/ports/> Perl release @@ -2283,7 +2300,7 @@ binaries available via http://www.cpan.org/ports/ Tandem Guardian 5.004 The following platforms have only binaries available via -http://www.cpan.org/ports/index.html : +L<http://www.cpan.org/ports/index.html> : Perl release @@ -2294,7 +2311,7 @@ http://www.cpan.org/ports/index.html : Although we do suggest that you always build your own Perl from the source code, both for maximal configurability and for security, in case you are in a hurry you can check -http://www.cpan.org/ports/index.html for binary distributions. +L<http://www.cpan.org/ports/index.html> for binary distributions. =head1 SEE ALSO @@ -2341,5 +2358,5 @@ Gurusamy Sarathy <gsar@activestate.com>, Paul J. Schinder <schinder@pobox.com>, Michael G Schwern <schwern@pobox.com>, Dan Sugalski <dan@sidhe.org>, -Nathan Torkington <gnat@frii.com>. +Nathan Torkington <gnat@frii.com>, John Malmberg <wb8tyw@qsl.net> diff --git a/Master/tlpkg/tlperl/lib/pods/perlqnx.pod b/Master/tlpkg/tlperl/lib/pods/perlqnx.pod index 0ad269a2725..cf9dc1fd958 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlqnx.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlqnx.pod @@ -86,7 +86,7 @@ they both point to the correct library, that is, The following tests may report errors under QNX4: -cpan/Cwd/Cwd.t will complain if `pwd` and cwd don't give +dist/Cwd/Cwd.t will complain if `pwd` and cwd don't give the same results. cwd calls `fullpath -t`, so if you cd `fullpath -t` before running the test, it will pass. diff --git a/Master/tlpkg/tlperl/lib/pods/perlre.pod b/Master/tlpkg/tlperl/lib/pods/perlre.pod index 527da4cb38a..c4ec417a1d2 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlre.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlre.pod @@ -51,13 +51,41 @@ X<regular expression, case-insensitive> Do case-insensitive pattern matching. -If C<use locale> is in effect, the case map is taken from the current -locale. See L<perllocale>. +If locale matching rules are in effect, the case map is taken from the +current +locale for code points less than 255, and from Unicode rules for larger +code points. However, matches that would cross the Unicode +rules/non-Unicode rules boundary (ords 255/256) will not succeed. See +L<perllocale>. + +There are a number of Unicode characters that match multiple characters +under C</i>. For example, C<LATIN SMALL LIGATURE FI> +should match the sequence C<fi>. Perl is not +currently able to do this when the multiple characters are in the pattern and +are split between groupings, or when one or more are quantified. Thus + + "\N{LATIN SMALL LIGATURE FI}" =~ /fi/i; # Matches + "\N{LATIN SMALL LIGATURE FI}" =~ /[fi][fi]/i; # Doesn't match! + "\N{LATIN SMALL LIGATURE FI}" =~ /fi*/i; # Doesn't match! + + # The below doesn't match, and it isn't clear what $1 and $2 would + # be even if it did!! + "\N{LATIN SMALL LIGATURE FI}" =~ /(f)(i)/i; # Doesn't match! + +Perl doesn't match multiple characters in an inverted bracketed +character class, which otherwise could be highly confusing. See +L<perlrecharclass/Negation>. + +Also, Perl matching doesn't fully conform to the current Unicode C</i> +recommendations, which ask that the matching be made upon the NFD +(Normalization Form Decomposed) of the text. However, Unicode is +in the process of reconsidering and revising their recommendations. =item x X</x> Extend your pattern's legibility by permitting whitespace and comments. +Details in L</"/x"> =item p X</p> X<regex, preserve> X<regexp, preserve> @@ -74,14 +102,26 @@ rather than the regex itself. See L<perlretut/"Using regular expressions in Perl"> for further explanation of the g and c modifiers. +=item a, d, l and u +X</a> X</d> X</l> X</u> + +These modifiers, new in 5.14, affect which character-set semantics +(Unicode, ASCII, etc.) are used, as described below in +L</Character set modifiers>. + =back These are usually written as "the C</x> modifier", even though the delimiter -in question might not really be a slash. Any of these -modifiers may also be embedded within the regular expression itself using -the C<(?...)> construct. See below. +in question might not really be a slash. The modifiers C</imsxadlup> +may also be embedded within the regular expression itself using +the C<(?...)> construct, see L</Extended Patterns> below. + +The C</x>, C</l>, C</u>, C</a> and C</d> modifiers need a little more +explanation. -The C</x> modifier itself needs a little more explanation. It tells +=head3 /x + +C</x> tells the regular expression parser to ignore most whitespace that is neither backslashed nor within a character class. You can use this to break up your regular expression into (slightly) more readable parts. The C<#> @@ -96,7 +136,7 @@ be careful not to include the pattern delimiter in the comment--perl has no way of knowing you did not intend to close the pattern early. See the C-comment deletion code in L<perlop>. Also note that anything inside a C<\Q...\E> stays unaffected by C</x>. And note that C</x> doesn't affect -whether space interpretation within a single multi-character construct. For +space interpretation within a single multi-character construct. For example in C<\x{...}>, regardless of the C</x> modifier, there can be no spaces. Same for a L<quantifier|/Quantifiers> such as C<{3}> or C<{5,}>. Similarly, C<(?:...)> can't have a space between the C<?> and C<:>, @@ -104,10 +144,229 @@ but can between the C<(> and C<?>. Within any delimiters for such a construct, allowed spaces are not affected by C</x>, and depend on the construct. For example, C<\x{...}> can't have spaces because hexadecimal numbers don't have spaces in them. But, Unicode properties can have spaces, so -in C<\p{...}> there can be spaces that follow the Unicode rules, for which see +in C<\p{...}> there can be spaces that follow the Unicode rules, for which see L<perluniprops/Properties accessible through \p{} and \P{}>. X</x> +=head3 Character set modifiers + +C</d>, C</u>, C</a>, and C</l>, available starting in 5.14, are called +the character set modifiers; they affect the character set semantics +used for the regular expression. + +At any given time, exactly one of these modifiers is in effect. Once +compiled, the behavior doesn't change regardless of what rules are in +effect when the regular expression is executed. And if a regular +expression is interpolated into a larger one, the original's rules +continue to apply to it, and only it. + +Note that the modifiers affect only pattern matching, and do not extend +to any replacement done. For example, + + s/foo/\Ubar/l + +will uppercase "bar", but the C</l> does not affect how the C<\U> +operates. If C<use locale> is in effect, the C<\U> will use locale +rules; if C<use feature 'unicode_strings'> is in effect, it will +use Unicode rules, etc. + +=head4 /l + +means to use the current locale's rules (see L<perllocale>) when pattern +matching. For example, C<\w> will match the "word" characters of that +locale, and C<"/i"> case-insensitive matching will match according to +the locale's case folding rules. The locale used will be the one in +effect at the time of execution of the pattern match. This may not be +the same as the compilation-time locale, and can differ from one match +to another if there is an intervening call of the +L<setlocale() function|perllocale/The setlocale function>. + +Perl only supports single-byte locales. This means that code points +above 255 are treated as Unicode no matter what locale is in effect. +Under Unicode rules, there are a few case-insensitive matches that cross +the 255/256 boundary. These are disallowed under C</l>. For example, +0xFF does not caselessly match the character at 0x178, C<LATIN CAPITAL +LETTER Y WITH DIAERESIS>, because 0xFF may not be C<LATIN SMALL LETTER Y +WITH DIAERESIS> in the current locale, and Perl has no way of knowing if +that character even exists in the locale, much less what code point it +is. + +This modifier may be specified to be the default by C<use locale>, but +see L</Which character set modifier is in effect?>. +X</l> + +=head4 /u + +means to use Unicode rules when pattern matching. On ASCII platforms, +this means that the code points between 128 and 255 take on their +Latin-1 (ISO-8859-1) meanings (which are the same as Unicode's), whereas +in strict ASCII their meanings are undefined. Thus the platform +effectively becomes a Unicode platform, hence, for example, C<\w> will +match any of the more than 100_000 word characters in Unicode. + +Unlike most locales, which are specific to a language and country pair, +Unicode classifies all the characters that are letters I<somewhere> as +C<\w>. For example, your locale might not think that C<LATIN SMALL +LETTER ETH> is a letter (unless you happen to speak Icelandic), but +Unicode does. Similarly, all the characters that are decimal digits +somewhere in the world will match C<\d>; this is hundreds, not 10, +possible matches. And some of those digits look like some of the 10 +ASCII digits, but mean a different number, so a human could easily think +a number is a different quantity than it really is. For example, +C<BENGALI DIGIT FOUR> (U+09EA) looks very much like an +C<ASCII DIGIT EIGHT> (U+0038). And, C<\d+>, may match strings of digits +that are a mixture from different writing systems, creating a security +issue. L<Unicode::UCD/num()> can be used to sort this out. + +Also, case-insensitive matching works on the full set of Unicode +characters. The C<KELVIN SIGN>, for example matches the letters "k" and +"K"; and C<LATIN SMALL LIGATURE FF> matches the sequence "ff", which, +if you're not prepared, might make it look like a hexadecimal constant, +presenting another potential security issue. See +L<http://unicode.org/reports/tr36> for a detailed discussion of Unicode +security issues. + +On the EBCDIC platforms that Perl handles, the native character set is +equivalent to Latin-1. Thus this modifier changes behavior only when +the C<"/i"> modifier is also specified, and it turns out it affects only +two characters, giving them full Unicode semantics: the C<MICRO SIGN> +will match the Greek capital and small letters C<MU>, otherwise not; and +the C<LATIN CAPITAL LETTER SHARP S> will match any of C<SS>, C<Ss>, +C<sS>, and C<ss>, otherwise not. + +This modifier may be specified to be the default by C<use feature +'unicode_strings>, but see +L</Which character set modifier is in effect?>. +X</u> + +=head4 /a + +is the same as C</u>, except that C<\d>, C<\s>, C<\w>, and the +Posix character classes are restricted to matching in the ASCII range +only. That is, with this modifier, C<\d> always means precisely the +digits C<"0"> to C<"9">; C<\s> means the five characters C<[ \f\n\r\t]>; +C<\w> means the 63 characters C<[A-Za-z0-9_]>; and likewise, all the +Posix classes such as C<[[:print:]]> match only the appropriate +ASCII-range characters. + +This modifier is useful for people who only incidentally use Unicode. +With it, one can write C<\d> with confidence that it will only match +ASCII characters, and should the need arise to match beyond ASCII, you +can use C<\p{Digit}>, or C<\p{Word}> for C<\w>. There are similar +C<\p{...}> constructs that can match white space and Posix classes +beyond ASCII. See L<perlrecharclass/POSIX Character Classes>. + +As you would expect, this modifier causes, for example, C<\D> to mean +the same thing as C<[^0-9]>; in fact, all non-ASCII characters match +C<\D>, C<\S>, and C<\W>. C<\b> still means to match at the boundary +between C<\w> and C<\W>, using the C</a> definitions of them (similarly +for C<\B>). + +Otherwise, C</a> behaves like the C</u> modifier, in that +case-insensitive matching uses Unicode semantics; for example, "k" will +match the Unicode C<\N{KELVIN SIGN}> under C</i> matching, and code +points in the Latin1 range, above ASCII will have Unicode rules when it +comes to case-insensitive matching. + +To forbid ASCII/non-ASCII matches (like "k" with C<\N{KELVIN SIGN}>), +specify the "a" twice, for example C</aai> or C</aia> + +To reiterate, this modifier provides protection for applications that +don't wish to be exposed to all of Unicode. Specifying it twice +gives added protection. + +This modifier may be specified to be the default by C<use re '/a'> +or C<use re '/aa'>, but see +L</Which character set modifier is in effect?>. +X</a> +X</aa> + +=head4 /d + +This modifier means to use the "Default" native rules of the platform +except when there is cause to use Unicode rules instead, as follows: + +=over 4 + +=item 1 + +the target string is encoded in UTF-8; or + +=item 2 + +the pattern is encoded in UTF-8; or + +=item 3 + +the pattern explicitly mentions a code point that is above 255 (say by +C<\x{100}>); or + +=item 4 + +the pattern uses a Unicode name (C<\N{...}>); or + +=item 5 + +the pattern uses a Unicode property (C<\p{...}>) + +=back + +Another mnemonic for this modifier is "Depends", as the rules actually +used depend on various things, and as a result you can get unexpected +results. See L<perlunicode/The "Unicode Bug">. + +On ASCII platforms, the native rules are ASCII, and on EBCDIC platforms +(at least the ones that Perl handles), they are Latin-1. + +Here are some examples of how that works on an ASCII platform: + + $str = "\xDF"; # $str is not in UTF-8 format. + $str =~ /^\w/; # No match, as $str isn't in UTF-8 format. + $str .= "\x{0e0b}"; # Now $str is in UTF-8 format. + $str =~ /^\w/; # Match! $str is now in UTF-8 format. + chop $str; + $str =~ /^\w/; # Still a match! $str remains in UTF-8 format. + +=head4 Which character set modifier is in effect? + +Which of these modifiers is in effect at any given point in a regular +expression depends on a fairly complex set of interactions. As +explained below in L</Extended Patterns> it is possible to explicitly +specify modifiers that apply only to portions of a regular expression. +The innermost always has priority over any outer ones, and one applying +to the whole expression has priority over any of the default settings that are +described in the remainder of this section. + +The C<L<use re 'E<sol>foo'|re/'E<sol>flags' mode">> pragma can be used to set +default modifiers (including these) for regular expressions compiled +within its scope. This pragma has precedence over the other pragmas +listed below that change the defaults. + +Otherwise, C<L<use locale|perllocale>> sets the default modifier to C</l>; +and C<L<use feature 'unicode_strings|feature>> or +C<L<use 5.012|perlfunc/use VERSION>> (or higher) set the default to +C</u> when not in the same scope as either C<L<use locale|perllocale>> +or C<L<use bytes|bytes>>. Unlike the mechanisms mentioned above, these +affect operations besides regular expressions pattern matching, and so +give more consistent results with other operators, including using +C<\U>, C<\l>, etc. in substitution replacements. + +If none of the above apply, for backwards compatibility reasons, the +C</d> modifier is the one in effect by default. As this can lead to +unexpected results, it is best to specify which other rule set should be +used. + +=head4 Character set modifier behavior prior to Perl 5.14 + +Prior to 5.14, there were no explicit modifiers, but C</l> was implied +for regexes compiled within the scope of C<use locale>, and C</d> was +implied otherwise. However, interpolating a regex into a larger regex +would ignore the original compilation in favor of whatever was in effect +at the time of the second compilation. There were a number of +inconsistencies (bugs) with the C</d> modifier, where Unicode rules +would be used when inappropriate, and vice versa. C<\p{}> did not imply +Unicode rules, and neither did all occurrences of C<\N{}>, until 5.12. + =head2 Regular Expressions =head3 Metacharacters @@ -124,13 +383,13 @@ X<metacharacter> X<\> X<^> X<.> X<$> X<|> X<(> X<()> X<[> X<[]> - \ Quote the next metacharacter - ^ Match the beginning of the line - . Match any character (except newline) - $ Match the end of the line (or before newline at the end) - | Alternation - () Grouping - [] Bracketed Character class + \ Quote the next metacharacter + ^ Match the beginning of the line + . Match any character (except newline) + $ Match the end of the line (or before newline at the end) + | Alternation + () Grouping + [] Bracketed Character class By default, the "^" character is guaranteed to match only the beginning of the string, the "$" character only the end (or before the @@ -142,7 +401,7 @@ newline within the string (except if the newline is the last character in the string), and "$" will match before any newline. At the cost of a little more overhead, you can do this by using the /m modifier on the pattern match operator. (Older programs did this by setting C<$*>, -but this practice has been removed in perl 5.9.) +but this option was removed in perl 5.9.) X<^> X<$> X</m> To simplify multi-line substitutions, the "." character never matches a @@ -155,14 +414,15 @@ X<.> X</s> The following standard quantifiers are recognized: X<metacharacter> X<quantifier> X<*> X<+> X<?> X<{n}> X<{n,}> X<{n,m}> - * Match 0 or more times - + Match 1 or more times - ? Match 1 or 0 times - {n} Match exactly n times - {n,} Match at least n times - {n,m} Match at least n but not more than m times + * Match 0 or more times + + Match 1 or more times + ? Match 1 or 0 times + {n} Match exactly n times + {n,} Match at least n times + {n,m} Match at least n but not more than m times -(If a curly bracket occurs in any other context, it is treated +(If a curly bracket occurs in any other context and does not form part of +a backslashed sequence like C<\x{...}>, it is treated as a regular character. In particular, the lower bound is not optional.) The "*" quantifier is equivalent to C<{0,}>, the "+" quantifier to C<{1,}>, and the "?" quantifier to C<{0,1}>. n and m are limited @@ -180,24 +440,24 @@ that the meanings don't change, just the "greediness": X<metacharacter> X<greedy> X<greediness> X<?> X<*?> X<+?> X<??> X<{n}?> X<{n,}?> X<{n,m}?> - *? Match 0 or more times, not greedily - +? Match 1 or more times, not greedily - ?? Match 0 or 1 time, not greedily - {n}? Match exactly n times, not greedily - {n,}? Match at least n times, not greedily - {n,m}? Match at least n but not more than m times, not greedily + *? Match 0 or more times, not greedily + +? Match 1 or more times, not greedily + ?? Match 0 or 1 time, not greedily + {n}? Match exactly n times, not greedily (redundant) + {n,}? Match at least n times, not greedily + {n,m}? Match at least n but not more than m times, not greedily By default, when a quantified subpattern does not allow the rest of the overall pattern to match, Perl will backtrack. However, this behaviour is sometimes undesirable. Thus Perl provides the "possessive" quantifier form as well. - *+ Match 0 or more times and give nothing back - ++ Match 1 or more times and give nothing back - ?+ Match 0 or 1 time and give nothing back - {n}+ Match exactly n times and give nothing back (redundant) - {n,}+ Match at least n times and give nothing back - {n,m}+ Match at least n but not more than m times and give nothing back + *+ Match 0 or more times and give nothing back + ++ Match 1 or more times and give nothing back + ?+ Match 0 or 1 time and give nothing back + {n}+ Match exactly n times and give nothing back (redundant) + {n,}+ Match at least n times and give nothing back + {n,m}+ Match at least n but not more than m times and give nothing back For instance, @@ -212,7 +472,8 @@ string" problem can be most efficiently performed when written as: /"(?:[^"\\]++|\\.)*+"/ as we know that if the final quote does not match, backtracking will not -help. See the independent subexpression C<< (?>...) >> for more details; +help. See the independent subexpression +L</C<< (?>pattern) >>> for more details; possessive quantifiers are just syntactic sugar for that construct. For instance the above example could also be written as follows: @@ -220,27 +481,26 @@ instance the above example could also be written as follows: =head3 Escape sequences -Because patterns are processed as double quoted strings, the following +Because patterns are processed as double-quoted strings, the following also work: - \t tab (HT, TAB) - \n newline (LF, NL) - \r return (CR) - \f form feed (FF) - \a alarm (bell) (BEL) - \e escape (think troff) (ESC) - \033 octal char (example: ESC) - \x1B hex char (example: ESC) - \x{263a} long hex char (example: Unicode SMILEY) - \cK control char (example: VT) - \N{name} named Unicode character - \N{U+263D} Unicode character (example: FIRST QUARTER MOON) - \l lowercase next char (think vi) - \u uppercase next char (think vi) - \L lowercase till \E (think vi) - \U uppercase till \E (think vi) - \Q quote (disable) pattern metacharacters till \E - \E end either case modification or quoted section (think vi) + \t tab (HT, TAB) + \n newline (LF, NL) + \r return (CR) + \f form feed (FF) + \a alarm (bell) (BEL) + \e escape (think troff) (ESC) + \cK control char (example: VT) + \x{}, \x00 character whose ordinal is the given hexadecimal number + \N{name} named Unicode character or character sequence + \N{U+263D} Unicode character (example: FIRST QUARTER MOON) + \o{}, \000 character whose ordinal is the given octal number + \l lowercase next char (think vi) + \u uppercase next char (think vi) + \L lowercase till \E (think vi) + \U uppercase till \E (think vi) + \Q quote (disable) pattern metacharacters till \E + \E end either case modification or quoted section, think vi Details are in L<perlop/Quote and Quote-like Operators>. @@ -249,43 +509,46 @@ Details are in L<perlop/Quote and Quote-like Operators>. In addition, Perl defines the following: X<\g> X<\k> X<\K> X<backreference> - Sequence Note Description - [...] [1] Match a character according to the rules of the bracketed - character class defined by the "...". Example: [a-z] - matches "a" or "b" or "c" ... or "z" - [[:...:]] [2] Match a character according to the rules of the POSIX - character class "..." within the outer bracketed character - class. Example: [[:upper:]] matches any uppercase - character. - \w [3] Match a "word" character (alphanumeric plus "_") - \W [3] Match a non-"word" character - \s [3] Match a whitespace character - \S [3] Match a non-whitespace character - \d [3] Match a decimal digit character - \D [3] Match a non-digit character - \pP [3] Match P, named property. Use \p{Prop} for longer names. - \PP [3] Match non-P - \X [4] Match Unicode "eXtended grapheme cluster" - \C Match a single C-language char (octet) even if that is part - of a larger UTF-8 character. Thus it breaks up characters - into their UTF-8 bytes, so you may end up with malformed - pieces of UTF-8. Unsupported in lookbehind. - \1 [5] Backreference to a specific capture buffer or group. - '1' may actually be any positive integer. - \g1 [5] Backreference to a specific or previous group, - \g{-1} [5] The number may be negative indicating a relative previous - buffer and may optionally be wrapped in curly brackets for - safer parsing. - \g{name} [5] Named backreference - \k<name> [5] Named backreference - \K [6] Keep the stuff left of the \K, don't include it in $& - \N [7] Any character but \n (experimental). Not affected by /s - modifier - \v [3] Vertical whitespace - \V [3] Not vertical whitespace - \h [3] Horizontal whitespace - \H [3] Not horizontal whitespace - \R [4] Linebreak + Sequence Note Description + [...] [1] Match a character according to the rules of the + bracketed character class defined by the "...". + Example: [a-z] matches "a" or "b" or "c" ... or "z" + [[:...:]] [2] Match a character according to the rules of the POSIX + character class "..." within the outer bracketed + character class. Example: [[:upper:]] matches any + uppercase character. + \w [3] Match a "word" character (alphanumeric plus "_", plus + other connector punctuation chars plus Unicode + marks) + \W [3] Match a non-"word" character + \s [3] Match a whitespace character + \S [3] Match a non-whitespace character + \d [3] Match a decimal digit character + \D [3] Match a non-digit character + \pP [3] Match P, named property. Use \p{Prop} for longer names + \PP [3] Match non-P + \X [4] Match Unicode "eXtended grapheme cluster" + \C Match a single C-language char (octet) even if that is + part of a larger UTF-8 character. Thus it breaks up + characters into their UTF-8 bytes, so you may end up + with malformed pieces of UTF-8. Unsupported in + lookbehind. + \1 [5] Backreference to a specific capture group or buffer. + '1' may actually be any positive integer. + \g1 [5] Backreference to a specific or previous group, + \g{-1} [5] The number may be negative indicating a relative + previous group and may optionally be wrapped in + curly brackets for safer parsing. + \g{name} [5] Named backreference + \k<name> [5] Named backreference + \K [6] Keep the stuff left of the \K, don't include it in $& + \N [7] Any character but \n (experimental). Not affected by + /s modifier + \v [3] Vertical whitespace + \V [3] Not vertical whitespace + \h [3] Horizontal whitespace + \H [3] Not horizontal whitespace + \R [4] Linebreak =over 4 @@ -307,7 +570,7 @@ See L<perlrebackslash/Misc> for details. =item [5] -See L</Capture buffers> below for details. +See L</Capture groups> below for details. =item [6] @@ -316,9 +579,9 @@ See L</Extended Patterns> below for details. =item [7] Note that C<\N> has two meanings. When of the form C<\N{NAME}>, it matches the -character whose name is C<NAME>; and similarly when of the form -C<\N{U+I<wide hex char>}>, it matches the character whose Unicode ordinal is -I<wide hex char>. Otherwise it matches any character but C<\n>. +character or character sequence whose name is C<NAME>; and similarly +when of the form C<\N{U+I<hex>}>, it matches the character whose Unicode +code point is I<hex>. Otherwise it matches any character but C<\n>. =back @@ -355,19 +618,20 @@ The C<\G> assertion can be used to chain global matches (using C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">. It is also useful when writing C<lex>-like scanners, when you have several patterns that you want to match against consequent substrings -of your string, see the previous reference. The actual location +of your string; see the previous reference. The actual location where C<\G> will match can also be influenced by using C<pos()> as an lvalue: see L<perlfunc/pos>. Note that the rule for zero-length -matches is modified somewhat, in that contents to the left of C<\G> is +matches (see L</"Repeated Patterns Matching a Zero-length Substring">) +is modified somewhat, in that contents to the left of C<\G> are not counted when determining the length of the match. Thus the following will not match forever: X<\G> - $str = 'ABC'; - pos($str) = 1; - while (/.\G/g) { - print $&; - } + my $string = 'ABC'; + pos($string) = 1; + while ($string =~ /(.\G)/g) { + print $1; + } It will print 'A' and then terminate, as it considers the match to be zero-width, and thus will not match at the same position twice in a @@ -376,90 +640,124 @@ row. It is worth noting that C<\G> improperly used can result in an infinite loop. Take care when using patterns that include C<\G> in an alternation. -=head3 Capture buffers +=head3 Capture groups -The bracketing construct C<( ... )> creates capture buffers. To refer -to the current contents of a buffer later on, within the same pattern, -use \1 for the first, \2 for the second, and so on. -Outside the match use "$" instead of "\". (The -\<digit> notation works in certain circumstances outside -the match. See L</Warning on \1 Instead of $1> below for details.) -Referring back to another part of the match is called a -I<backreference>. +The bracketing construct C<( ... )> creates capture groups (also referred to as +capture buffers). To refer to the current contents of a group later on, within +the same pattern, use C<\g1> (or C<\g{1}>) for the first, C<\g2> (or C<\g{2}>) +for the second, and so on. +This is called a I<backreference>. X<regex, capture buffer> X<regexp, capture buffer> +X<regex, capture group> X<regexp, capture group> X<regular expression, capture buffer> X<backreference> - -There is no limit to the number of captured substrings that you may -use. However Perl also uses \10, \11, etc. as aliases for \010, -\011, etc. (Recall that 0 means octal, so \011 is the character at -number 9 in your coded character set; which would be the 10th character, -a horizontal tab under ASCII.) Perl resolves this -ambiguity by interpreting \10 as a backreference only if at least 10 -left parentheses have opened before it. Likewise \11 is a -backreference only if at least 11 left parentheses have opened -before it. And so on. \1 through \9 are always interpreted as -backreferences. -If the bracketing group did not match, the associated backreference won't -match either. (This can happen if the bracketing group is optional, or -in a different branch of an alternation.) - +X<regular expression, capture group> X<backreference> X<\g{1}> X<\g{-1}> X<\g{name}> X<relative backreference> X<named backreference> -In order to provide a safer and easier way to construct patterns using -backreferences, Perl provides the C<\g{N}> notation (starting with perl -5.10.0). The curly brackets are optional, however omitting them is less -safe as the meaning of the pattern can be changed by text (such as digits) -following it. When N is a positive integer the C<\g{N}> notation is -exactly equivalent to using normal backreferences. When N is a negative -integer then it is a relative backreference referring to the previous N'th -capturing group. When the bracket form is used and N is not an integer, it -is treated as a reference to a named buffer. - -Thus C<\g{-1}> refers to the last buffer, C<\g{-2}> refers to the -buffer before that. For example: +X<named capture buffer> X<regular expression, named capture buffer> +X<named capture group> X<regular expression, named capture group> +X<%+> X<$+{name}> X<< \k<name> >> +There is no limit to the number of captured substrings that you may use. +Groups are numbered with the leftmost open parenthesis being number 1, etc. If +a group did not match, the associated backreference won't match either. (This +can happen if the group is optional, or in a different branch of an +alternation.) +You can omit the C<"g">, and write C<"\1">, etc, but there are some issues with +this form, described below. + +You can also refer to capture groups relatively, by using a negative number, so +that C<\g-1> and C<\g{-1}> both refer to the immediately preceding capture +group, and C<\g-2> and C<\g{-2}> both refer to the group before it. For +example: / - (Y) # buffer 1 - ( # buffer 2 - (X) # buffer 3 - \g{-1} # backref to buffer 3 - \g{-3} # backref to buffer 1 + (Y) # group 1 + ( # group 2 + (X) # group 3 + \g{-1} # backref to group 3 + \g{-3} # backref to group 1 ) /x -and would match the same as C</(Y) ( (X) \3 \1 )/x>. - -Additionally, as of Perl 5.10.0 you may use named capture buffers and named -backreferences. The notation is C<< (?<name>...) >> to declare and C<< \k<name> >> -to reference. You may also use apostrophes instead of angle brackets to delimit the -name; and you may use the bracketed C<< \g{name} >> backreference syntax. -It's possible to refer to a named capture buffer by absolute and relative number as well. -Outside the pattern, a named capture buffer is available via the C<%+> hash. -When different buffers within the same pattern have the same name, C<$+{name}> -and C<< \k<name> >> refer to the leftmost defined group. (Thus it's possible -to do things with named capture buffers that would otherwise require C<(??{})> -code to accomplish.) -X<named capture buffer> X<regular expression, named capture buffer> -X<%+> X<$+{name}> X<< \k<name> >> +would match the same as C</(Y) ( (X) \g3 \g1 )/x>. This allows you to +interpolate regexes into larger regexes and not have to worry about the +capture groups being renumbered. + +You can dispense with numbers altogether and create named capture groups. +The notation is C<(?E<lt>I<name>E<gt>...)> to declare and C<\g{I<name>}> to +reference. (To be compatible with .Net regular expressions, C<\g{I<name>}> may +also be written as C<\k{I<name>}>, C<\kE<lt>I<name>E<gt>> or C<\k'I<name>'>.) +I<name> must not begin with a number, nor contain hyphens. +When different groups within the same pattern have the same name, any reference +to that name assumes the leftmost defined group. Named groups count in +absolute and relative numbering, and so can also be referred to by those +numbers. +(It's possible to do things with named capture groups that would otherwise +require C<(??{})>.) + +Capture group contents are dynamically scoped and available to you outside the +pattern until the end of the enclosing block or until the next successful +match, whichever comes first. (See L<perlsyn/"Compound Statements">.) +You can refer to them by absolute number (using C<"$1"> instead of C<"\g1">, +etc); or by name via the C<%+> hash, using C<"$+{I<name>}">. + +Braces are required in referring to named capture groups, but are optional for +absolute or relative numbered ones. Braces are safer when creating a regex by +concatenating smaller strings. For example if you have C<qr/$a$b/>, and C<$a> +contained C<"\g1">, and C<$b> contained C<"37">, you would get C</\g137/> which +is probably not what you intended. + +The C<\g> and C<\k> notations were introduced in Perl 5.10.0. Prior to that +there were no named nor relative numbered capture groups. Absolute numbered +groups were referred to using C<\1>, +C<\2>, etc., and this notation is still +accepted (and likely always will be). But it leads to some ambiguities if +there are more than 9 capture groups, as C<\10> could mean either the tenth +capture group, or the character whose ordinal in octal is 010 (a backspace in +ASCII). Perl resolves this ambiguity by interpreting C<\10> as a backreference +only if at least 10 left parentheses have opened before it. Likewise C<\11> is +a backreference only if at least 11 left parentheses have opened before it. +And so on. C<\1> through C<\9> are always interpreted as backreferences. +There are several examples below that illustrate these perils. You can avoid +the ambiguity by always using C<\g{}> or C<\g> if you mean capturing groups; +and for octal constants always using C<\o{}>, or for C<\077> and below, using 3 +digits padded with leading zeros, since a leading zero implies an octal +constant. + +The C<\I<digit>> notation also works in certain circumstances outside +the pattern. See L</Warning on \1 Instead of $1> below for details. Examples: s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words - /(.)\1/ # find first doubled char + /(.)\g1/ # find first doubled char and print "'$1' is the first doubled character\n"; /(?<char>.)\k<char>/ # ... a different way and print "'$+{char}' is the first doubled character\n"; - /(?'char'.)\1/ # ... mix and match + /(?'char'.)\g1/ # ... mix and match and print "'$1' is the first doubled character\n"; if (/Time: (..):(..):(..)/) { # parse out values - $hours = $1; - $minutes = $2; - $seconds = $3; + $hours = $1; + $minutes = $2; + $seconds = $3; } + /(.)(.)(.)(.)(.)(.)(.)(.)(.)\g10/ # \g10 is a backreference + /(.)(.)(.)(.)(.)(.)(.)(.)(.)\10/ # \10 is octal + /((.)(.)(.)(.)(.)(.)(.)(.)(.))\10/ # \10 is a backreference + /((.)(.)(.)(.)(.)(.)(.)(.)(.))\010/ # \010 is octal + + $a = '(.)\1'; # Creates problems when concatenated. + $b = '(.)\g{1}'; # Avoids the problems. + "aa" =~ /${a}/; # True + "aa" =~ /${b}/; # True + "aa0" =~ /${a}0/; # False! + "aa0" =~ /${b}0/; # True + "aa\x08" =~ /${a}0/; # True! + "aa\x08" =~ /${b}0/; # False + Several special variables also refer back to portions of the previous match. C<$+> returns whatever the last bracket match matched. C<$&> returns the entire matched string. (At one point C<$0> did @@ -471,14 +769,13 @@ extended patterns (see below), for example to assign a submatch to a variable. X<$+> X<$^N> X<$&> X<$`> X<$'> -The numbered match variables ($1, $2, $3, etc.) and the related punctuation -set (C<$+>, C<$&>, C<$`>, C<$'>, and C<$^N>) are all dynamically scoped +These special variables, like the C<%+> hash and the numbered match variables +(C<$1>, C<$2>, C<$3>, etc.) are dynamically scoped until the end of the enclosing block or until the next successful match, whichever comes first. (See L<perlsyn/"Compound Statements">.) X<$+> X<$^N> X<$&> X<$`> X<$'> X<$1> X<$2> X<$3> X<$4> X<$5> X<$6> X<$7> X<$8> X<$9> - B<NOTE>: Failed matches in Perl do not reset the match variables, which makes it easier to write code that tests for a series of more specific cases and remembers the best match. @@ -486,7 +783,7 @@ specific cases and remembers the best match. B<WARNING>: Once Perl sees that you need one of C<$&>, C<$`>, or C<$'> anywhere in the program, it has to provide them for every pattern match. This may substantially slow your program. Perl -uses the same mechanism to produce $1, $2, etc, so you also pay a +uses the same mechanism to produce C<$1>, C<$2>, etc, so you also pay a price for each pattern that contains capturing parentheses. (To avoid this cost while retaining the grouping behaviour, use the extended regular expression C<(?: ... )> instead.) But if you never @@ -536,7 +833,8 @@ consult L<perlop/"Gory details of parsing quoted constructs">. =head2 Extended Patterns Perl also defines a consistent extension syntax for features not -found in standard tools like B<awk> and B<lex>. The syntax is a +found in standard tools like B<awk> and +B<lex>. The syntax for most of these is a pair of parentheses with a question mark as the first thing within the parentheses. The character after the question mark indicates the extension. @@ -550,7 +848,7 @@ status. A question mark was chosen for this and for the minimal-matching construct because 1) question marks are rare in older regular expressions, and 2) whenever you see one, you should stop and -"question" exactly what is going on. That's psychology... +"question" exactly what is going on. That's psychology.... =over 10 @@ -562,16 +860,19 @@ whitespace formatting, a simple C<#> will suffice. Note that Perl closes the comment as soon as it sees a C<)>, so there is no way to put a literal C<)> in the comment. -=item C<(?pimsx-imsx)> -X<(?)> +=item C<(?adlupimsx-imsx)> + +=item C<(?^alupimsx)> +X<(?)> X<(?^)> One or more embedded pattern-match modifiers, to be turned on (or turned off, if preceded by C<->) for the remainder of the pattern or -the remainder of the enclosing pattern group (if any). This is -particularly useful for dynamic patterns, such as those read in from a +the remainder of the enclosing pattern group (if any). + +This is particularly useful for dynamic patterns, such as those read in from a configuration file, taken from an argument, or specified in a table -somewhere. Consider the case where some patterns want to be case -sensitive and some do not: The case insensitive ones merely need to +somewhere. Consider the case where some patterns want to be +case-sensitive and some do not: The case-insensitive ones merely need to include C<(?i)> at the front of the pattern. For example: $pattern = "foobar"; @@ -584,7 +885,7 @@ include C<(?i)> at the front of the pattern. For example: These modifiers are restored at the end of the enclosing group. For example, - ( (?i) blah ) \s+ \1 + ( (?i) blah ) \s+ \g1 will match C<blah> in any case, some spaces, and an exact (I<including the case>!) repetition of the previous word, assuming the C</x> modifier, and no C</i> @@ -594,15 +895,33 @@ These modifiers do not carry over into named subpatterns called in the enclosing group. In other words, a pattern such as C<((?i)(&NAME))> does not change the case-sensitivity of the "NAME" pattern. -Note that the C<p> modifier is special in that it can only be enabled, -not disabled, and that its presence anywhere in a pattern has a global -effect. Thus C<(?-p)> and C<(?-p:...)> are meaningless and will warn -when executed under C<use warnings>. +Any of these modifiers can be set to apply globally to all regular +expressions compiled within the scope of a C<use re>. See +L<re/"'/flags' mode">. + +Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately +after the C<"?"> is a shorthand equivalent to C<d-imsx>. Flags (except +C<"d">) may follow the caret to override it. +But a minus sign is not legal with it. + +Note that the C<a>, C<d>, C<l>, C<p>, and C<u> modifiers are special in +that they can only be enabled, not disabled, and the C<a>, C<d>, C<l>, and +C<u> modifiers are mutually exclusive: specifying one de-specifies the +others, and a maximum of one (or two C<a>'s) may appear in the +construct. Thus, for +example, C<(?-p)> will warn when compiled under C<use warnings>; +C<(?-d:...)> and C<(?dl:...)> are fatal errors. + +Note also that the C<p> modifier is special in that its presence +anywhere in a pattern has a global effect. =item C<(?:pattern)> X<(?:)> -=item C<(?imsx-imsx:pattern)> +=item C<(?adluimsx-imsx:pattern)> + +=item C<(?^aluimsx:pattern)> +X<(?^:)> This is for clustering, not capturing; it groups subexpressions like "()", but doesn't make backreferences as "()" does. So @@ -617,7 +936,7 @@ but doesn't spit out extra fields. It's also cheaper not to capture characters if you don't need to. Any letters between C<?> and C<:> act as flags modifiers as with -C<(?imsx-imsx)>. For example, +C<(?adluimsx-imsx)>. For example, /(?s-i:more.*than).*million/i @@ -625,26 +944,57 @@ is equivalent to the more verbose /(?:(?s-i)more.*than).*million/i +Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately +after the C<"?"> is a shorthand equivalent to C<d-imsx>. Any positive +flags (except C<"d">) may follow the caret, so + + (?^x:foo) + +is equivalent to + + (?x-ims:foo) + +The caret tells Perl that this cluster doesn't inherit the flags of any +surrounding pattern, but uses the system defaults (C<d-imsx>), +modified by any flags specified. + +The caret allows for simpler stringification of compiled regular +expressions. These look like + + (?^:pattern) + +with any non-default flags appearing between the caret and the colon. +A test that looks at such stringification thus doesn't need to have the +system default flags hard-coded in it, just the caret. If new flags are +added to Perl, the meaning of the caret's expansion will change to include +the default for those flags, so the test will still work, unchanged. + +Specifying a negative flag after the caret is an error, as the flag is +redundant. + +Mnemonic for C<(?^...)>: A fresh beginning since the usual use of a caret is +to match at the beginning. + =item C<(?|pattern)> X<(?|)> X<Branch reset> This is the "branch reset" pattern, which has the special property -that the capture buffers are numbered from the same starting point +that the capture groups are numbered from the same starting point in each alternation branch. It is available starting from perl 5.10.0. -Capture buffers are numbered from left to right, but inside this +Capture groups are numbered from left to right, but inside this construct the numbering is restarted for each branch. -The numbering within each branch will be as normal, and any buffers +The numbering within each branch will be as normal, and any groups following this construct will be numbered as though the construct contained only one branch, that being the one with the most capture -buffers in it. +groups in it. -This construct will be useful when you want to capture one of a +This construct is useful when you want to capture one of a number of alternative matches. Consider the following pattern. The numbers underneath show in -which buffer the captured content will be stored. +which group the captured content will be stored. # before ---------------branch-reset----------- after @@ -653,7 +1003,7 @@ which buffer the captured content will be stored. Be careful when using the branch reset pattern in combination with named captures. Named captures are implemented as being aliases to -numbered buffers holding the captures, and that interferes with the +numbered groups holding the captures, and that interferes with the implementation of the branch reset pattern. If you are using named captures in a branch reset pattern, it's best to use the same names, in the same order, in each of the alternations: @@ -667,13 +1017,13 @@ Not doing so may lead to surprises: say $+ {a}; # Prints '12' say $+ {b}; # *Also* prints '12'. -The problem here is that both the buffer named C<< a >> and the buffer -named C<< b >> are aliases for the buffer belonging to C<< $1 >>. +The problem here is that both the group named C<< a >> and the group +named C<< b >> are aliases for the group belonging to C<< $1 >>. =item Look-Around Assertions X<look-around assertion> X<lookaround assertion> X<look-around> X<lookaround> -Look-around assertions are zero width patterns which match a specific +Look-around assertions are zero-width patterns which match a specific pattern without including it in C<$&>. Positive assertions match when their subpattern matches, negative assertions match when their subpattern fails. Look-behind matches text up to the current match position, @@ -698,14 +1048,7 @@ use this for look-behind. If you are looking for a "bar" that isn't preceded by a "foo", C</(?!foo)bar/> will not do what you want. That's because the C<(?!foo)> is just saying that the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will -match. You would have to do something like C</(?!foo)...bar/> for that. We -say "like" because there's the case of your "bar" not having three characters -before it. You could cover that this way: C</(?:(?!foo)...|^.{0,2})bar/>. -Sometimes it's still easier just to say: - - if (/bar/ && $` !~ /foo$/) - -For look-behind see below. +match. Use look-behind instead (see below). =item C<(?<=pattern)> C<\K> X<(?<=)> X<look-behind, positive> X<lookbehind, positive> X<\K> @@ -716,7 +1059,7 @@ Works only for fixed-width look-behind. There is a special form of this construct, called C<\K>, which causes the regex engine to "keep" everything it had matched prior to the C<\K> and -not include it in C<$&>. This effectively provides variable length +not include it in C<$&>. This effectively provides variable-length look-behind. The use of C<\K> inside of another look-around assertion is allowed, but the behaviour is currently not well defined. @@ -745,18 +1088,20 @@ only for fixed-width look-behind. =item C<< (?<NAME>pattern) >> X<< (?<NAME>) >> X<(?'NAME')> X<named capture> X<capture> -A named capture buffer. Identical in every respect to normal capturing -parentheses C<()> but for the additional fact that C<%+> or C<%-> may be -used after a successful match to refer to a named buffer. See C<perlvar> +A named capture group. Identical in every respect to normal capturing +parentheses C<()> but for the additional fact that the group +can be referred to by name in various regular expression +constructs (like C<\g{NAME}>) and can be accessed by name +after a successful match via C<%+> or C<%->. See L<perlvar> for more details on the C<%+> and C<%-> hashes. -If multiple distinct capture buffers have the same name then the -$+{NAME} will refer to the leftmost defined buffer in the match. +If multiple distinct capture groups have the same name then the +$+{NAME} will refer to the leftmost defined group in the match. The forms C<(?'NAME'pattern)> and C<< (?<NAME>pattern) >> are equivalent. B<NOTE:> While the notation of this construct is the same as the similar -function in .NET regexes, the behavior is not. In Perl the buffers are +function in .NET regexes, the behavior is not. In Perl the groups are numbered sequentially regardless of being named or not. Thus in the pattern @@ -823,16 +1168,16 @@ C<local>ization are undone, so that $_ = 'a' x 8; m< - (?{ $cnt = 0 }) # Initialize $cnt. + (?{ $cnt = 0 }) # Initialize $cnt. ( a (?{ - local $cnt = $cnt + 1; # Update $cnt, backtracking-safe. + local $cnt = $cnt + 1; # Update $cnt, backtracking-safe. }) )* aaaa - (?{ $res = $cnt }) # On success copy to non-localized - # location. + (?{ $res = $cnt }) # On success copy to + # non-localized location. >x; will set C<$res = 4>. Note that after the match, C<$cnt> returns to the globally @@ -852,8 +1197,8 @@ L<"Backtracking">. For reasons of security, this construct is forbidden if the regular expression involves run-time interpolation of variables, unless the perilous C<use re 'eval'> pragma has been used (see L<re>), or the -variables contain results of C<qr//> operator (see -L<perlop/"qr/STRINGE<sol>msixpo">). +variables contain results of the C<qr//> operator (see +L<perlop/"qr/STRINGE<sol>msixpodual">). This restriction is due to the wide-spread and remarkably convenient custom of using run-time determined strings as patterns. For example: @@ -874,10 +1219,11 @@ B<WARNING>: Use of lexical (C<my>) variables in these blocks is broken. The result is unpredictable and will make perl unstable. The workaround is to use global (C<our>) variables. -B<WARNING>: Because Perl's regex engine is currently not re-entrant, -interpolated code may not invoke the regex engine either directly with +B<WARNING>: In perl 5.12.x and earlier, the regex engine +was not re-entrant, so interpolated code could not +safely invoke the regex engine either directly with C<m//> or C<s///>), or indirectly with functions such as -C<split>. Invoking the regex engine in these blocks will make perl +C<split>. Invoking the regex engine in these blocks would make perl unstable. =item C<(??{ code })> @@ -891,11 +1237,11 @@ due to the effect of future optimisations in the regex engine. This is a "postponed" regular subexpression. The C<code> is evaluated at run time, at the moment this subexpression may match. The result -of evaluation is considered as a regular expression and matched as +of evaluation is considered a regular expression and matched as if it were inserted instead of this construct. Note that this means -that the contents of capture buffers defined inside an eval'ed pattern +that the contents of capture groups defined inside an eval'ed pattern are not available outside of the pattern, and vice versa, there is no -way for the inner pattern to refer to a capture buffer defined outside. +way for the inner pattern to refer to a capture group defined outside. Thus, ('a' x 100)=~/(??{'(.)' x 100})/ @@ -908,14 +1254,14 @@ where the C<code> ends are currently somewhat convoluted. The following pattern matches a parenthesized group: $re = qr{ - \( - (?: - (?> [^()]+ ) # Non-parens without backtracking - | - (??{ $re }) # Group with matching parens - )* - \) - }x; + \( + (?: + (?> [^()]+ ) # Non-parens without backtracking + | + (??{ $re }) # Group with matching parens + )* + \) + }x; See also C<(?PARNO)> for a different, more efficient way to accomplish the same task. @@ -923,12 +1269,12 @@ the same task. For reasons of security, this construct is forbidden if the regular expression involves run-time interpolation of variables, unless the perilous C<use re 'eval'> pragma has been used (see L<re>), or the -variables contain results of C<qr//> operator (see -L<perlop/"qrE<sol>STRINGE<sol>msixpo">). +variables contain results of the C<qr//> operator (see +L<perlop/"qrE<sol>STRINGE<sol>msixpodual">). -Because perl's regex engine is not currently re-entrant, delayed -code may not invoke the regex engine either directly with C<m//> or C<s///>), -or indirectly with functions such as C<split>. +In perl 5.12.x and earlier, because the regex engine was not re-entrant, +delayed code could not safely invoke the regex engine either directly with +C<m//> or C<s///>), or indirectly with functions such as C<split>. Recursing deeper than 50 times without consuming any input string will result in a fatal error. The maximum depth is compiled into perl, so @@ -940,20 +1286,20 @@ X<regex, recursive> X<regexp, recursive> X<regular expression, recursive> X<regex, relative recursion> Similar to C<(??{ code })> except it does not involve compiling any code, -instead it treats the contents of a capture buffer as an independent -pattern that must match at the current position. Capture buffers +instead it treats the contents of a capture group as an independent +pattern that must match at the current position. Capture groups contained by the pattern will have the value as determined by the outermost recursion. PARNO is a sequence of digits (not starting with 0) whose value reflects -the paren-number of the capture buffer to recurse to. C<(?R)> recurses to +the paren-number of the capture group to recurse to. C<(?R)> recurses to the beginning of the whole pattern. C<(?0)> is an alternate syntax for C<(?R)>. If PARNO is preceded by a plus or minus sign then it is assumed -to be relative, with negative numbers indicating preceding capture buffers +to be relative, with negative numbers indicating preceding capture groups and positive ones following. Thus C<(?-1)> refers to the most recently -declared buffer, and C<(?+1)> indicates the next buffer to be declared. +declared group, and C<(?+1)> indicates the next group to be declared. Note that the counting for relative recursion differs from that of -relative backreferences, in that with recursion unclosed buffers B<are> +relative backreferences, in that with recursion unclosed groups B<are> included. The following pattern matches a function foo() which may contain @@ -988,7 +1334,7 @@ the output produced should be the following: $2 = (bar(baz)+baz(bop)) $3 = bar(baz)+baz(bop) -If there is no corresponding capture buffer defined, then it is a +If there is no corresponding capture group defined, then it is a fatal error. Recursing deeper than 50 times without consuming any input string will also result in a fatal error. The maximum depth is compiled into perl, so changing it requires a custom build. @@ -1028,10 +1374,14 @@ X<(?()> =item C<(?(condition)yes-pattern)> -Conditional expression. C<(condition)> should be either an integer in +Conditional expression. Matches C<yes-pattern> if C<condition> yields +a true value, matches C<no-pattern> otherwise. A missing pattern always +matches. + +C<(condition)> should be either an integer in parentheses (which is valid if the corresponding pair of parentheses matched), a look-ahead/look-behind/evaluate zero-width assertion, a -name in angle brackets or single quotes (which is valid if a buffer +name in angle brackets or single quotes (which is valid if a group with the given name matched), or the special symbol (R) (true when evaluated inside of recursion or eval). Additionally the R may be followed by a number, (which will be true when evaluated when recursing @@ -1044,15 +1394,20 @@ Here's a summary of the possible predicates: =item (1) (2) ... -Checks if the numbered capturing buffer has matched something. +Checks if the numbered capturing group has matched something. =item (<NAME>) ('NAME') -Checks if a buffer with the given name has matched something. +Checks if a group with the given name has matched something. + +=item (?=...) (?!...) (?<=...) (?<!...) + +Checks whether the pattern matches (or does not match, for the '!' +variants). =item (?{ CODE }) -Treats the code block as the condition. +Treats the return value of the code block as the condition. =item (R) @@ -1092,9 +1447,9 @@ For example: matches a chunk of non-parentheses, possibly included in parentheses themselves. -A special form is the C<(DEFINE)> predicate, which never executes directly -its yes-pattern, and does not allow a no-pattern. This allows to define -subpatterns which will be executed only by using the recursion mechanism. +A special form is the C<(DEFINE)> predicate, which never executes its +yes-pattern directly, and does not allow a no-pattern. This allows one to +define subpatterns which will be executed only by the recursion mechanism. This way, you can define a set of regular expression rules that can be bundled into any pattern you choose. @@ -1113,8 +1468,8 @@ An example of how this might be used is as follows: (?<ADRESS_PAT>....) )/x -Note that capture buffers matched inside of recursion are not accessible -after the recursion returns, so the extra layer of capturing buffers is +Note that capture groups matched inside of recursion are not accessible +after the recursion returns, so the extra layer of capturing groups is necessary. Thus C<$+{NAME_PAT}> would not be defined even though C<$+{NAME}> would be. @@ -1138,9 +1493,13 @@ group C<ab> (see L<"Backtracking">). In particular, C<a*> inside C<a*ab> will match fewer characters than a standalone C<a*>, since this makes the tail match. +C<< (?>pattern) >> does not disable backtracking altogether once it has +matched. It is still possible to backtrack past the construct, but not +into it. So C<< ((?>a*)|(?>b*))ar >> will still match "bar". + An effect similar to C<< (?>pattern) >> may be achieved by writing -C<(?=(pattern))\1>. This matches the same substring as a standalone -C<a+>, and the following C<\1> eats the matched string; it therefore +C<(?=(pattern))\g{-1}>. This matches the same substring as a standalone +C<a+>, and the following C<\g{-1}> eats the matched string; it therefore makes a zero-length assertion into an analogue of C<< (?>...) >>. (The difference between these two constructs is that the second one uses a capturing group, thus shifting ordinals of backreferences @@ -1150,7 +1509,7 @@ Consider this pattern: m{ \( ( - [^()]+ # x+ + [^()]+ # x+ | \( [^()]* \) )+ @@ -1170,7 +1529,7 @@ hung. However, a tiny change to this pattern m{ \( ( - (?> [^()]+ ) # change x+ above to (?> x+ ) + (?> [^()]+ ) # change x+ above to (?> x+ ) | \( [^()]* \) )+ @@ -1180,7 +1539,8 @@ hung. However, a tiny change to this pattern which uses C<< (?>...) >> matches exactly when the one above does (verifying this yourself would be a productive exercise), but finishes in a fourth the time when used on a similar string with 1000000 C<a>s. Be aware, -however, that this pattern currently triggers a warning message under +however, that, when this construct is followed by a +quantifier, it currently triggers a warning message under the C<use warnings> pragma or B<-w> switch saying it C<"matches null string many times in regex">. @@ -1251,7 +1611,7 @@ C<(*MARK:NAME)> pattern executed. See the explanation for the C<(*MARK:NAME)> verb below for more details. B<NOTE:> C<$REGERROR> and C<$REGMARK> are not magic variables like C<$1> -and most other regex related variables. They are not local to a scope, nor +and most other regex-related variables. They are not local to a scope, nor readonly, but instead are volatile package variables similar to C<$AUTOLOAD>. Use C<local> to localize changes to them to a specific scope if necessary. @@ -1299,7 +1659,7 @@ If we add a C<(*PRUNE)> before the count like the following 'aaab' =~ /a+b?(*PRUNE)(?{print "$&\n"; $count++})(*FAIL)/; print "Count=$count\n"; -we prevent backtracking and find the count of the longest matching +we prevent backtracking and find the count of the longest matching string at each matching starting point like so: aaab @@ -1333,7 +1693,7 @@ encountered, then the C<(*SKIP)> operator has no effect. When used without a name the "skip point" is where the match point was when executing the (*SKIP) pattern. -Compare the following to the examples in C<(*PRUNE)>, note the string +Compare the following to the examples in C<(*PRUNE)>; note the string is twice as long: 'aaabaaab' =~ /a+b?(*SKIP)(?{print "$&\n"; $count++})(*FAIL)/; @@ -1368,7 +1728,7 @@ name of the most recently executed C<(*MARK:NAME)> that was involved in the match. This can be used to determine which branch of a pattern was matched -without using a separate capture buffer for each branch, which in turn +without using a separate capture group for each branch, which in turn can result in a performance improvement, as perl cannot optimize C</(?:(x)|(y)|(z))/> as efficiently as something like C</(?:x(*MARK:x)|y(*MARK:y)|z(*MARK:z))/>. @@ -1463,14 +1823,14 @@ whether there is actually more to match in the string. When inside of a nested pattern, such as recursion, or in a subpattern dynamically generated via C<(??{})>, only the innermost pattern is ended immediately. -If the C<(*ACCEPT)> is inside of capturing buffers then the buffers are +If the C<(*ACCEPT)> is inside of capturing groups then the groups are marked as ended at the point at which the C<(*ACCEPT)> was encountered. For instance: 'AB' =~ /(A (A|B(*ACCEPT)|C) D)(E)/x; will match, and C<$1> will be C<AB> and C<$2> will be C<B>, C<$3> will not -be set. If another branch in the inner parentheses were matched, such as in the +be set. If another branch in the inner parentheses was matched, such as in the string 'ACDE', then the C<D> and C<E> would have to be matched as well. =back @@ -1502,7 +1862,7 @@ word following "foo" in the string "Food is on the foo table.": $_ = "Food is on the foo table."; if ( /\b(foo)\s+(\w+)/i ) { - print "$2 follows $1.\n"; + print "$2 follows $1.\n"; } When the match runs, the first part of the regular expression (C<\b(foo)>) @@ -1520,7 +1880,7 @@ like this: $_ = "The food is under the bar in the barn."; if ( /foo(.*)bar/ ) { - print "got <$1>\n"; + print "got <$1>\n"; } Which perhaps unexpectedly yields: @@ -1540,8 +1900,8 @@ of a string, and you also want to keep the preceding part of the match. So you write this: $_ = "I have 2 numbers: 53147"; - if ( /(.*)(\d*)/ ) { # Wrong! - print "Beginning is <$1>, number is <$2>.\n"; + if ( /(.*)(\d*)/ ) { # Wrong! + print "Beginning is <$1>, number is <$2>.\n"; } That won't work at all, because C<.*> was greedy and gobbled up the @@ -1554,23 +1914,23 @@ Here are some variants, most of which don't work: $_ = "I have 2 numbers: 53147"; @pats = qw{ - (.*)(\d*) - (.*)(\d+) - (.*?)(\d*) - (.*?)(\d+) - (.*)(\d+)$ - (.*?)(\d+)$ - (.*)\b(\d+)$ - (.*\D)(\d+)$ + (.*)(\d*) + (.*)(\d+) + (.*?)(\d*) + (.*?)(\d+) + (.*)(\d+)$ + (.*?)(\d+)$ + (.*)\b(\d+)$ + (.*\D)(\d+)$ }; for $pat (@pats) { - printf "%-12s ", $pat; - if ( /$pat/ ) { - print "<$1> <$2>\n"; - } else { - print "FAIL\n"; - } + printf "%-12s ", $pat; + if ( /$pat/ ) { + print "<$1> <$2>\n"; + } else { + print "FAIL\n"; + } } That will print out: @@ -1596,8 +1956,8 @@ trickier. Imagine you'd like to find a sequence of non-digits not followed by "123". You might try to write that as $_ = "ABC123"; - if ( /^\D*(?!123)/ ) { # Wrong! - print "Yup, no 123 in $_\n"; + if ( /^\D*(?!123)/ ) { # Wrong! + print "Yup, no 123 in $_\n"; } But that isn't going to match; at least, not the way you're hoping. It @@ -1629,7 +1989,7 @@ let C<\D*> expand to "ABC", this would have caused the whole pattern to fail. The search engine will initially match C<\D*> with "ABC". Then it will -try to match C<(?!123> with "123", which fails. But because +try to match C<(?!123)> with "123", which fails. But because a quantifier (C<\D*>) has been used in the regular expression, the search engine can backtrack and retry the match differently in the hope of matching the complete regular expression. @@ -1677,12 +2037,12 @@ match takes a long time to finish. A powerful tool for optimizing such beasts is what is known as an "independent group", -which does not backtrack (see L<C<< (?>pattern) >>>). Note also that +which does not backtrack (see L</C<< (?>pattern) >>>). Note also that zero-length look-ahead/look-behind assertions will not backtrack to make the tail match, since they are in "logical" context: only whether they match is considered relevant. For an example where side-effects of look-ahead I<might> have influenced the -following match, see L<C<< (?>pattern) >>>. +following match, see L</C<< (?>pattern) >>>. =head2 Version 8 Regular Expressions X<regular expression, version 8> X<regex, version 8> X<regexp, version 8> @@ -1698,7 +2058,7 @@ character; "\\" matches a "\"). This escape mechanism is also required for the character used as the pattern delimiter. A series of characters matches that series of characters in the target -string, so the pattern C<blurfl> would match "blurfl" in the target +string, so the pattern C<blurfl> would match "blurfl" in the target string. You can specify a character class, by enclosing a list of characters @@ -1727,9 +2087,9 @@ spell out the character sets in full. Characters may be specified using a metacharacter syntax much like that used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return, "\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string -of octal digits, matches the character whose coded character set value +of three octal digits, matches the character whose coded character set value is I<nnn>. Similarly, \xI<nn>, where I<nn> are hexadecimal digits, -matches the character whose numeric value is I<nn>. The expression \cI<x> +matches the character whose ordinal is I<nn>. The expression \cI<x> matches the character control-I<x>. Finally, the "." metacharacter matches any character except "\n" (unless you use C</s>). @@ -1737,9 +2097,9 @@ You can specify a series of alternatives for a pattern using "|" to separate them, so that C<fee|fie|foe> will match any of "fee", "fie", or "foe" in the target string (as would C<f(e|i|o)e>). The first alternative includes everything from the last pattern delimiter -("(", "[", or the beginning of the pattern) up to the first "|", and +("(", "(?:", etc. or the beginning of the pattern) up to the first "|", and the last alternative contains everything from the last "|" to the next -pattern delimiter. That's why it's common practice to include +closing pattern delimiter. That's why it's common practice to include alternatives in parentheses: to minimize confusion about where they start and end. @@ -1757,10 +2117,10 @@ so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>. Within a pattern, you may designate subpatterns for later reference by enclosing them in parentheses, and you may refer back to the I<n>th subpattern later in the pattern using the metacharacter -\I<n>. Subpatterns are numbered based on the left to right order +\I<n> or \gI<n>. Subpatterns are numbered based on the left to right order of their opening parenthesis. A backreference matches whatever actually matched the subpattern in the string being examined, not -the rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will +the rules for that subpattern. Therefore, C<(0|0x)\d*\s\g1\d*> will match "0x1234 0x4321", but not "0x1234 01234", because subpattern 1 matched "0x", even though the rule C<0|0x> could potentially match the leading 0 in the second number. @@ -1780,7 +2140,7 @@ meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit of doing that, you get yourself into trouble if you then add an C</e> modifier. - s/(\d+)/ \1 + 1 /eg; # causes warning under -w + s/(\d+)/ \1 + 1 /eg; # causes warning under -w Or if you try to do @@ -1821,7 +2181,7 @@ However, long experience has shown that many programming tasks may be significantly simplified by using repeated subexpressions that may match zero-length substrings. Here's a simple example being: - @chars = split //, $string; # // is not magic in split + @chars = split //, $string; # // is not magic in split ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// / Thus Perl allows such constructs, by I<forcefully breaking @@ -1837,12 +2197,34 @@ zero-length substring. Thus is made equivalent to - m{ (?: NON_ZERO_LENGTH )* - | - (?: ZERO_LENGTH )? - }x; + m{ (?: NON_ZERO_LENGTH )* (?: ZERO_LENGTH )? }x; + +For example, this program -The higher level-loops preserve an additional state between iterations: + #!perl -l + "aaaaab" =~ / + (?: + a # non-zero + | # or + (?{print "hello"}) # print hello whenever this + # branch is tried + (?=(b)) # zero-width assertion + )* # any number of times + /x; + print $&; + print $1; + +prints + + hello + aaaaa + b + +Notice that "hello" is only printed once, as when Perl sees that the sixth +iteration of the outermost C<(?:)*> matches a zero-length string, it stops +the C<*>. + +The higher-level loops preserve an additional state between iterations: whether the last match was zero-length. To break the loop, the following match after a zero-length match is prohibited to have a length of zero. This prohibition interacts with backtracking (see L<"Backtracking">), @@ -1873,7 +2255,7 @@ Each of the elementary pieces of regular expressions which were described before (such as C<ab> or C<\Z>) could match at most one substring at the given position of the input string. However, in a typical regular expression these elementary pieces are combined into more complicated -patterns using combining operators C<ST>, C<S|T>, C<S*> etc +patterns using combining operators C<ST>, C<S|T>, C<S*> etc. (in these examples C<S> and C<T> are regular subexpressions). Such combinations can include alternatives, leading to a problem of choice: @@ -1902,11 +2284,11 @@ Consider two possible matches, C<AB> and C<A'B'>, C<A> and C<A'> are substrings which can be matched by C<S>, C<B> and C<B'> are substrings which can be matched by C<T>. -If C<A> is better match for C<S> than C<A'>, C<AB> is a better +If C<A> is a better match for C<S> than C<A'>, C<AB> is a better match than C<A'B'>. If C<A> and C<A'> coincide: C<AB> is a better match than C<AB'> if -C<B> is better match for C<T> than C<B'>. +C<B> is a better match for C<T> than C<B'>. =item C<S|T> @@ -1953,7 +2335,7 @@ only whether or not C<S> can match is important. =item C<(??{ EXPR })>, C<(?PARNO)> The ordering is the same as for the regular expression which is -the result of EXPR, or the pattern contained by capture buffer PARNO. +the result of EXPR, or the pattern contained by capture group PARNO. =item C<(?(condition)yes-pattern|no-pattern)> @@ -1970,8 +2352,13 @@ than a match at a later position. =head2 Creating Custom RE Engines -Overloaded constants (see L<overload>) provide a simple way to extend -the functionality of the RE engine. +As of Perl 5.10.0, one can create custom regular expression engines. This +is not for the faint of heart, as they have to plug in at the C level. See +L<perlreapi> for more details. + +As an alternative, overloaded constants (see L<overload>) provide a simple +way to extend the functionality of the RE engine, by substituting one +pattern for another. Suppose that we want to enable a new RE escape-sequence C<\Y|> which matches at a boundary between whitespace characters and non-whitespace @@ -1994,7 +2381,7 @@ this: # We must also take care of not escaping the legitimate \\Y| # sequence, hence the presence of '\\' in the conversion rules. my %rules = ( '\\' => '\\\\', - 'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ ); + 'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ ); sub convert { my $re = shift; $re =~ s{ @@ -2017,41 +2404,35 @@ part of this regular expression needs to be converted explicitly $re = customre::convert $re; /\Y|$re\Y|/; -=head1 PCRE/Python Support +=head2 PCRE/Python Support -As of Perl 5.10.0, Perl supports several Python/PCRE specific extensions +As of Perl 5.10.0, Perl supports several Python/PCRE-specific extensions to the regex syntax. While Perl programmers are encouraged to use the -Perl specific syntax, the following are also accepted: +Perl-specific syntax, the following are also accepted: =over 4 =item C<< (?PE<lt>NAMEE<gt>pattern) >> -Define a named capture buffer. Equivalent to C<< (?<NAME>pattern) >>. +Define a named capture group. Equivalent to C<< (?<NAME>pattern) >>. =item C<< (?P=NAME) >> -Backreference to a named capture buffer. Equivalent to C<< \g{NAME} >>. +Backreference to a named capture group. Equivalent to C<< \g{NAME} >>. =item C<< (?P>NAME) >> -Subroutine call to a named capture buffer. Equivalent to C<< (?&NAME) >>. +Subroutine call to a named capture group. Equivalent to C<< (?&NAME) >>. =back =head1 BUGS -There are numerous problems with case insensitive matching of characters -outside the ASCII range, especially with those whose folds are multiple -characters, such as ligatures like C<LATIN SMALL LIGATURE FF>. - -In a bracketed character class with case insensitive matching, ranges only work -for ASCII characters. For example, -C<m/[\N{CYRILLIC CAPITAL LETTER A}-\N{CYRILLIC CAPITAL LETTER YA}]/i> -doesn't match all the Russian upper and lower case letters. - Many regular expression constructs don't work on EBCDIC platforms. +There are a number of issues with regard to case-insensitive matching +in Unicode rules. See C<i> under L</Modifiers> above. + This document varies from difficult to understand to completely and utterly opaque. The wandering prose riddled with jargon is hard to fathom in several places. diff --git a/Master/tlpkg/tlperl/lib/pods/perlreapi.pod b/Master/tlpkg/tlperl/lib/pods/perlreapi.pod index d1d947b8a74..1c694a72318 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlreapi.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlreapi.pod @@ -120,21 +120,26 @@ TODO: Document those cases. =item C</p> - RXf_PMf_KEEPCOPY +=item Character set + +The character set semantics are determined by an enum that is contained +in this field. This is still experimental and subject to change, but +the current interface returns the rules by use of the in-line function +C<get_regex_charset(const U32 flags)>. The only currently documented +value returned from it is REGEX_LOCALE_CHARSET, which is set if +C<use locale> is in effect. If present in C<< rx->extflags >> +C<split> will use the locale dependent definition of whitespace under +when RXf_SKIPWHITE or RXf_WHITE are in effect. Under ASCII whitespace +is defined as per L<isSPACE|perlapi/isSPACE>, and by the internal +macros C<is_utf8_space> under UTF-8 and C<isSPACE_LC> under C<use +locale>. + =back Additional flags: =over 4 -=item RXf_PMf_LOCALE - -Set if C<use locale> is in effect. If present in C<< rx->extflags >> -C<split> will use the locale dependent definition of whitespace under -when RXf_SKIPWHITE or RXf_WHITE are in effect. Under ASCII whitespace -is defined as per L<isSPACE|perlapi/ISSPACE>, and by the internal -macros C<is_utf8_space> under UTF-8 and C<isSPACE_LC> under C<use -locale>. - =item RXf_UTF8 Set if the pattern is L<SvUTF8()|perlapi/SvUTF8>, set by Perl_pmruntime. @@ -243,7 +248,7 @@ perl will handle releasing anything else contained in the regexp structure. Called to get/set the value of C<$`>, C<$'>, C<$&> and their named equivalents, ${^PREMATCH}, ${^POSTMATCH} and $^{MATCH}, as well as the -numbered capture buffers (C<$1>, C<$2>, ...). +numbered capture groups (C<$1>, C<$2>, ...). The C<paren> parameter will be C<-2> for C<$`>, C<-1> for C<$'>, C<0> for C<$&>, C<1> for C<$1> and so forth. @@ -317,7 +322,7 @@ behave in the same situation: package main; - tie my $sv => "CatptureVar"; + tie my $sv => "CaptureVar"; $sv =~ y/a/b/; Because C<$sv> is C<undef> when the C<y///> operator is applied to it @@ -492,7 +497,7 @@ values. in the final match, used for optimisations */ struct reg_substr_data *substrs; - U32 nparens; /* number of capture buffers */ + U32 nparens; /* number of capture groups */ /* private engine specific data */ U32 intflags; /* Engine Specific Internal flags */ @@ -612,7 +617,7 @@ C<regexp_paren_pair> struct is defined as follows: } regexp_paren_pair; If C<< ->offs[num].start >> or C<< ->offs[num].end >> is C<-1> then that -capture buffer did not match. C<< ->offs[0].start/end >> represents C<$&> (or +capture group did not match. C<< ->offs[0].start/end >> represents C<$&> (or C<${^MATCH> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where C<$paren >= 1>. @@ -633,7 +638,7 @@ The relevant snippet from C<Perl_pp_regcomp>: =head2 C<paren_names> -This is a hash used internally to track named capture buffers and their +This is a hash used internally to track named capture groups and their offsets. The keys are the names of the buffers the values are dualvars, with the IV slot holding the number of buffers with the given name and the pv being an embedded array of I32. The values may also be contained @@ -655,7 +660,7 @@ Used during execution phase for managing search and replace patterns. =head2 C<wrapped> C<wraplen> Stores the string C<qr//> stringifies to. The perl engine for example -stores C<(?-xism:eek)> in the case of C<qr/eek/>. +stores C<(?^:eek)> in the case of C<qr/eek/>. When using a custom engine that doesn't support the C<(?:)> construct for inline modifiers, it's probably best to have C<qr//> stringify to diff --git a/Master/tlpkg/tlperl/lib/pods/perlrebackslash.pod b/Master/tlpkg/tlperl/lib/pods/perlrebackslash.pod index 489ba2b648f..8f2490d78ee 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlrebackslash.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlrebackslash.pod @@ -25,14 +25,14 @@ or it is the start of a backslash or escape sequence. The rules determining what it is are quite simple: if the character following the backslash is an ASCII punctuation (non-word) character (that is, -anything that is not a letter, digit or underscore), then the backslash just -takes away the special meaning (if any) of the character following it. +anything that is not a letter, digit, or underscore), then the backslash just +takes away any special meaning of the character following it. If the character following the backslash is an ASCII letter or an ASCII digit, then the sequence may be special; if so, it's listed below. A few letters have not been used yet, so escaping them with a backslash doesn't change them to be special. A future version of Perl may assign a special meaning to them, so if -you have warnings turned on, Perl will issue a warning if you use such a +you have warnings turned on, Perl issues a warning if you use such a sequence. [1]. It is however guaranteed that backslash or escape sequences never have a @@ -48,9 +48,9 @@ backslash. =item [1] -There is one exception. If you use an alphanumerical character as the +There is one exception. If you use an alphanumeric character as the delimiter of your pattern (which you probably shouldn't do for readability -reasons), you will have to escape the delimiter if you want to match +reasons), you have to escape the delimiter if you want to match it. Perl won't warn then. See also L<perlop/Gory details of parsing quoted constructs>. @@ -62,7 +62,7 @@ quoted constructs>. Those not usable within a bracketed character class (like C<[\da-z]>) are marked as C<Not in [].> - \000 Octal escape sequence. + \000 Octal escape sequence. See also \o{}. \1 Absolute backreference. Not in []. \a Alarm or bell. \A Beginning of string. Not in []. @@ -75,7 +75,7 @@ as C<Not in [].> \e Escape character. \E Turn off \Q, \L and \U processing. Not in []. \f Form feed. - \g{}, \g1 Named, absolute or relative backreference. Not in []. + \g{}, \g1 Named, absolute or relative backreference. Not in [] \G Pos assertion. Not in []. \h Character class for horizontal whitespace. \H Character class for non horizontal whitespace. @@ -85,7 +85,8 @@ as C<Not in [].> \L Lowercase till \E. Not in []. \n (Logical) newline character. \N Any character but newline. Experimental. Not in []. - \N{} Named or numbered (Unicode) character. + \N{} Named or numbered (Unicode) character or sequence. + \o{} Octal escape sequence. \p{}, \pP Character with the given Unicode property. \P{}, \PP Character without the given Unicode property. \Q Quotemeta till \E. Not in []. @@ -133,7 +134,7 @@ character class, C<\b> is a word/non-word boundary. =item [2] -C<\n> matches a logical newline. Perl will convert between C<\n> and your +C<\n> matches a logical newline. Perl converts between C<\n> and your OS's native newline character when reading from or writing to text files. =back @@ -164,38 +165,39 @@ Mnemonic: I<c>ontrol character. $str =~ /\cK/; # Matches if $str contains a vertical tab (control-K). -=head3 Named or numbered characters +=head3 Named or numbered characters and character sequences -Unicode characters have a Unicode name and numeric ordinal value. Use the +Unicode characters have a Unicode name and numeric code point (ordinal) +value. Use the C<\N{}> construct to specify a character by either of these values. +Certain sequences of characters also have names. -To specify by name, the name of the character goes between the curly braces. -In this case, you have to C<use charnames> to load the Unicode names of the -characters, otherwise Perl will complain. +To specify by name, the name of the character or character sequence goes +between the curly braces. In this case, you have to C<use charnames> to +load the Unicode names of the characters; otherwise Perl will complain. -To specify by Unicode ordinal number, use the form -C<\N{U+I<wide hex character>}>, where I<wide hex character> is a number in -hexadecimal that gives the ordinal number that Unicode has assigned to the -desired character. It is customary (but not required) to use leading zeros to -pad the number to 4 digits. Thus C<\N{U+0041}> means -C<Latin Capital Letter A>, and you will rarely see it written without the two -leading zeros. C<\N{U+0041}> means "A" even on EBCDIC machines (where the -ordinal value of "A" is not 0x41). +To specify a character by Unicode code point, use the form C<\N{U+I<code +point>}>, where I<code point> is a number in hexadecimal that gives the +code point that Unicode has assigned to the desired character. It is +customary but not required to use leading zeros to pad the number to 4 +digits. Thus C<\N{U+0041}> means C<LATIN CAPITAL LETTER A>, and you will +rarely see it written without the two leading zeros. C<\N{U+0041}> means +"A" even on EBCDIC machines (where the ordinal value of "A" is not 0x41). -It is even possible to give your own names to characters, and even to short -sequences of characters. For details, see L<charnames>. +It is even possible to give your own names to characters and character +sequences. For details, see L<charnames>. (There is an expanded internal form that you may see in debug output: -C<\N{U+I<wide hex character>.I<wide hex character>...}>. -The C<...> means any number of these I<wide hex character>s separated by dots. +C<\N{U+I<code point>.I<code point>...}>. +The C<...> means any number of these I<code point>s separated by dots. This represents the sequence formed by the characters. This is an internal form only, subject to change, and you should not try to use it yourself.) Mnemonic: I<N>amed character. -Note that a character that is expressed as a named or numbered character is -considered as a character without special meaning by the regex engine, and will -match "as is". +Note that a character or character sequence expressed as a named +or numbered character is considered a character without special +meaning by the regex engine, and will match "as is". =head4 Example @@ -207,30 +209,56 @@ match "as is". =head3 Octal escapes -Octal escapes consist of a backslash followed by two or three octal digits -matching the code point of the character you want to use. This allows for -512 characters (C<\00> up to C<\777>) that can be expressed this way (but -anything above C<\377> is deprecated). -Enough in pre-Unicode days, but most Unicode characters cannot be escaped -this way. - -Note that a character that is expressed as an octal escape is considered -as a character without special meaning by the regex engine, and will match +There are two forms of octal escapes. Each is used to specify a character by +its code point specified in octal notation. + +One form, available starting in Perl 5.14 looks like C<\o{...}>, where the dots +represent one or more octal digits. It can be used for any Unicode character. + +It was introduced to avoid the potential problems with the other form, +available in all Perls. That form consists of a backslash followed by three +octal digits. One problem with this form is that it can look exactly like an +old-style backreference (see +L</Disambiguation rules between old-style octal escapes and backreferences> +below.) You can avoid this by making the first of the three digits always a +zero, but that makes \077 the largest code point specifiable. + +In some contexts, a backslash followed by two or even one octal digits may be +interpreted as an octal escape, sometimes with a warning, and because of some +bugs, sometimes with surprising results. Also, if you are creating a regex +out of smaller snippets concatenated together, and you use fewer than three +digits, the beginning of one snippet may be interpreted as adding digits to the +ending of the snippet before it. See L</Absolute referencing> for more +discussion and examples of the snippet problem. + +Note that a character expressed as an octal escape is considered +a character without special meaning by the regex engine, and will match "as is". -=head4 Examples (assuming an ASCII platform) +To summarize, the C<\o{}> form is always safe to use, and the other form is +safe to use for code points through \077 when you use exactly three digits to +specify them. - $str = "Perl"; - $str =~ /\120/; # Match, "\120" is "P". - $str =~ /\120+/; # Match, "\120" is "P", it is repeated at least once. - $str =~ /P\053/; # No match, "\053" is "+" and taken literally. +Mnemonic: I<0>ctal or I<o>ctal. -=head4 Caveat +=head4 Examples (assuming an ASCII platform) -Octal escapes potentially clash with backreferences. They both consist -of a backslash followed by numbers. So Perl has to use heuristics to -determine whether it is a backreference or an octal escape. Perl uses -the following rules: + $str = "Perl"; + $str =~ /\o{120}/; # Match, "\120" is "P". + $str =~ /\120/; # Same. + $str =~ /\o{120}+/; # Match, "\120" is "P", it's repeated at least once + $str =~ /\120+/; # Same. + $str =~ /P\053/; # No match, "\053" is "+" and taken literally. + /\o{23073}/ # Black foreground, white background smiling face. + /\o{4801234567}/ # Raises a warning, and yields chr(4) + +=head4 Disambiguation rules between old-style octal escapes and backreferences + +Octal escapes of the C<\000> form outside of bracketed character classes +potentially clash with old-style backreferences. (see L</Absolute referencing> +below). They both consist of a backslash followed by numbers. So Perl has to +use heuristics to determine whether it is a backreference or an octal escape. +Perl uses the following rules to disambiguate: =over 4 @@ -244,30 +272,35 @@ If the first digit following the backslash is a 0, it's an octal escape. =item 3 -If the number following the backslash is N (in decimal), and Perl already has -seen N capture groups, Perl will consider this to be a backreference. -Otherwise, it will consider it to be an octal escape. Note that if N has more -than three digits, Perl only takes the first three for the octal escape; -the rest are matched as is. +If the number following the backslash is N (in decimal), and Perl already +has seen N capture groups, Perl considers this a backreference. Otherwise, +it considers it an octal escape. If N has more than three digits, Perl +takes only the first three for the octal escape; the rest are matched as is. my $pat = "(" x 999; $pat .= "a"; $pat .= ")" x 999; /^($pat)\1000$/; # Matches 'aa'; there are 1000 capture groups. /^$pat\1000$/; # Matches 'a@0'; there are 999 capture groups - # and \1000 is seen as \100 (a '@') and a '0'. + # and \1000 is seen as \100 (a '@') and a '0' =back +You can force a backreference interpretation always by using the C<\g{...}> +form. You can the force an octal interpretation always by using the C<\o{...}> +form, or for numbers up through \077 (= 63 decimal), by using three digits, +beginning with a "0". + =head3 Hexadecimal escapes -Hexadecimal escapes start with C<\x> and are then either followed by a -two digit hexadecimal number, or a hexadecimal number of arbitrary length -surrounded by curly braces. The hexadecimal number is the code point of -the character you want to express. +Like octal escapes, there are two forms of hexadecimal escapes, but both start +with the same thing, C<\x>. This is followed by either exactly two hexadecimal +digits forming a number, or a hexadecimal number of arbitrary length surrounded +by curly braces. The hexadecimal number is the code point of the character you +want to express. -Note that a character that is expressed as a hexadecimal escape is considered -as a character without special meaning by the regex engine, and will match +Note that a character expressed as one of these escapes is considered a +character without special meaning by the regex engine, and will match "as is". Mnemonic: heI<x>adecimal. @@ -276,7 +309,7 @@ Mnemonic: heI<x>adecimal. $str = "Perl"; $str =~ /\x50/; # Match, "\x50" is "P". - $str =~ /\x50+/; # Match, "\x50" is "P", it is repeated at least once. + $str =~ /\x50+/; # Match, "\x50" is "P", it is repeated at least once $str =~ /P\x2B/; # No match, "\x2B" is "+" and taken literally. /\x{2603}\x{2602}/ # Snowman with an umbrella. @@ -290,20 +323,20 @@ Mnemonic: heI<x>adecimal. A number of backslash sequences have to do with changing the character, or characters following them. C<\l> will lowercase the character following it, while C<\u> will uppercase (or, more accurately, titlecase) the -character following it. (They perform similar functionality as the -functions C<lcfirst> and C<ucfirst>). +character following it. They provide functionality similar to the +functions C<lcfirst> and C<ucfirst>. To uppercase or lowercase several characters, one might want to use C<\L> or C<\U>, which will lowercase/uppercase all characters following -them, until either the end of the pattern, or the next occurrence of -C<\E>, whatever comes first. They perform similar functionality as the -functions C<lc> and C<uc> do. +them, until either the end of the pattern or the next occurrence of +C<\E>, whichever comes first. They provide functionality similar to what +the functions C<lc> and C<uc> provide. C<\Q> is used to escape all characters following, up to the next C<\E> or the end of the pattern. C<\Q> adds a backslash to any character that -isn't a letter, digit or underscore. This will ensure that any character -between C<\Q> and C<\E> is matched literally, and will not be interpreted -by the regexp engine. +isn't a letter, digit, or underscore. This ensures that any character +between C<\Q> and C<\E> shall be matched literally, not interpreted +as a metacharacter by the regex engine. Mnemonic: I<L>owercase, I<U>ppercase, I<Q>uotemeta, I<E>nd. @@ -324,15 +357,22 @@ the character classes are written as a backslash sequence. We will briefly discuss those here; full details of character classes can be found in L<perlrecharclass>. -C<\w> is a character class that matches any single I<word> character (letters, -digits, underscore). C<\d> is a character class that matches any decimal digit, -while the character class C<\s> matches any whitespace character. +C<\w> is a character class that matches any single I<word> character +(letters, digits, Unicode marks, and connector punctuation (like the +underscore)). C<\d> is a character class that matches any decimal +digit, while the character class C<\s> matches any whitespace character. New in perl 5.10.0 are the classes C<\h> and C<\v> which match horizontal and vertical whitespace characters. +The exact set of characters matched by C<\d>, C<\s>, and C<\w> varies +depending on various pragma and regular expression modifiers. It is +possible to restrict the match to the ASCII range by using the C</a> +regular expression modifier. See L<perlrecharclass>. + The uppercase variants (C<\W>, C<\D>, C<\S>, C<\H>, and C<\V>) are -character classes that match any character that isn't a word character, -digit, whitespace, horizontal whitespace nor vertical whitespace. +character classes that match, respectively, any character that isn't a +word character, digit, whitespace, horizontal whitespace, or vertical +whitespace. Mnemonics: I<w>ord, I<d>igit, I<s>pace, I<h>orizontal, I<v>ertical. @@ -348,7 +388,6 @@ L<perlunicode/Unicode Character Properties>. Mnemonic: I<p>roperty. - =head2 Referencing If capturing parenthesis are used in a regular expression, we can refer @@ -360,41 +399,51 @@ absolutely, relatively, and by name. =head3 Absolute referencing -A backslash sequence that starts with a backslash and is followed by a -number is an absolute reference (but be aware of the caveat mentioned above). -If the number is I<N>, it refers to the Nth set of parentheses - whatever -has been matched by that set of parenthesis has to be matched by the C<\N> -as well. +Either C<\gI<N>> (starting in Perl 5.10.0), or C<\I<N>> (old-style) where I<N> +is a positive (unsigned) decimal number of any length is an absolute reference +to a capturing group. + +I<N> refers to the Nth set of parentheses, so C<\gI<N>> refers to whatever has +been matched by that set of parentheses. Thus C<\g1> refers to the first +capture group in the regex. + +The C<\gI<N>> form can be equivalently written as C<\g{I<N>}> +which avoids ambiguity when building a regex by concatenating shorter +strings. Otherwise if you had a regex C<qr/$a$b/>, and C<$a> contained +C<"\g1">, and C<$b> contained C<"37">, you would get C</\g137/> which is +probably not what you intended. + +In the C<\I<N>> form, I<N> must not begin with a "0", and there must be at +least I<N> capturing groups, or else I<N> is considered an octal escape +(but something like C<\18> is the same as C<\0018>; that is, the octal escape +C<"\001"> followed by a literal digit C<"8">). + +Mnemonic: I<g>roup. =head4 Examples - /(\w+) \1/; # Finds a duplicated word, (e.g. "cat cat"). - /(.)(.)\2\1/; # Match a four letter palindrome (e.g. "ABBA"). + /(\w+) \g1/; # Finds a duplicated word, (e.g. "cat cat"). + /(\w+) \1/; # Same thing; written old-style + /(.)(.)\g2\g1/; # Match a four letter palindrome (e.g. "ABBA"). =head3 Relative referencing -New in perl 5.10.0 is a different way of referring to capture buffers: C<\g>. -C<\g> takes a number as argument, with the number in curly braces (the -braces are optional). If the number (N) does not have a sign, it's a reference -to the Nth capture group (so C<\g{2}> is equivalent to C<\2> - except that -C<\g> always refers to a capture group and will never be seen as an octal -escape). If the number is negative, the reference is relative, referring to -the Nth group before the C<\g{-N}>. +C<\g-I<N>> (starting in Perl 5.10.0) is used for relative addressing. (It can +be written as C<\g{-I<N>>.) It refers to the I<N>th group before the +C<\g{-I<N>}>. -The big advantage of C<\g{-N}> is that it makes it much easier to write +The big advantage of this form is that it makes it much easier to write patterns with references that can be interpolated in larger patterns, even if the larger pattern also contains capture groups. -Mnemonic: I<g>roup. - =head4 Examples - /(A) # Buffer 1 - ( # Buffer 2 - (B) # Buffer 3 - \g{-1} # Refers to buffer 3 (B) - \g{-3} # Refers to buffer 1 (A) + /(A) # Group 1 + ( # Group 2 + (B) # Group 3 + \g{-1} # Refers to group 3 (B) + \g{-3} # Refers to group 1 (A) ) /x; # Matches "ABBA". @@ -403,17 +452,15 @@ Mnemonic: I<g>roup. =head3 Named referencing -Also new in perl 5.10.0 is the use of named capture buffers, which can be -referred to by name. This is done with C<\g{name}>, which is a -backreference to the capture buffer with the name I<name>. +C<\g{I<name>}> (starting in Perl 5.10.0) can be used to back refer to a +named capture group, dispensing completely with having to think about capture +buffer positions. To be compatible with .Net regular expressions, C<\g{name}> may also be written as C<\k{name}>, C<< \k<name> >> or C<\k'name'>. -Note that C<\g{}> has the potential to be ambiguous, as it could be a named -reference, or an absolute or relative reference (if its argument is numeric). -However, names are not allowed to start with digits, nor are they allowed to -contain a hyphen, so there is no ambiguity. +To prevent any ambiguity, I<name> must not start with a digit nor contain a +hyphen. =head4 Examples @@ -434,7 +481,7 @@ backslash sequences. =item \A C<\A> only matches at the beginning of the string. If the C</m> modifier -isn't used, then C</\A/> is equivalent with C</^/>. However, if the C</m> +isn't used, then C</\A/> is equivalent to C</^/>. However, if the C</m> modifier is used, then C</^/> matches internal newlines, but the meaning of C</\A/> isn't changed by the C</m> modifier. C<\A> matches at the beginning of the string regardless whether the C</m> modifier is used. @@ -442,26 +489,27 @@ of the string regardless whether the C</m> modifier is used. =item \z, \Z C<\z> and C<\Z> match at the end of the string. If the C</m> modifier isn't -used, then C</\Z/> is equivalent with C</$/>, that is, it matches at the -end of the string, or before the newline at the end of the string. If the +used, then C</\Z/> is equivalent to C</$/>; that is, it matches at the +end of the string, or one before the newline at the end of the string. If the C</m> modifier is used, then C</$/> matches at internal newlines, but the meaning of C</\Z/> isn't changed by the C</m> modifier. C<\Z> matches at the end of the string (or just before a trailing newline) regardless whether the C</m> modifier is used. -C<\z> is just like C<\Z>, except that it will not match before a trailing -newline. C<\z> will only match at the end of the string - regardless of the -modifiers used, and not before a newline. +C<\z> is just like C<\Z>, except that it does not match before a trailing +newline. C<\z> matches at the end of the string only, regardless of the +modifiers used, and not just before a newline. It is how to anchor the +match to the true end of the string under all conditions. =item \G -C<\G> is usually only used in combination with the C</g> modifier. If the -C</g> modifier is used (and the match is done in scalar context), Perl will -remember where in the source string the last match ended, and the next time, +C<\G> is usually used only in combination with the C</g> modifier. If the +C</g> modifier is used and the match is done in scalar context, Perl +remembers where in the source string the last match ended, and the next time, it will start the match from where it ended the previous time. -C<\G> matches the point where the previous match ended, or the beginning -of the string if there was no previous match. +C<\G> matches the point where the previous match on that string ended, +or the beginning of that string if there was no previous match. =for later add link to perlremodifiers @@ -474,7 +522,17 @@ matches at any place between characters where C<\b> doesn't match. C<\b> and C<\B> assume there's a non-word character before the beginning and after the end of the source string; so C<\b> will match at the beginning (or end) of the source string if the source string begins (or ends) with a word -character. Otherwise, C<\B> will match. +character. Otherwise, C<\B> will match. + +Do not use something like C<\b=head\d\b> and expect it to match the +beginning of a line. It can't, because for there to be a boundary before +the non-word "=", there must be a word character immediately previous. +All boundary determinations look for word characters alone, not for +non-words characters nor for string ends. It may help to understand how +<\b> and <\B> work by equating them as follows: + + \b really means (?:(?<=\w)(?!\w)|(?<!\w)(?=\w)) + \B really means (?:(?<=\w)(?=\w)|(?<!\w)(?!\w)) Mnemonic: I<b>oundary. @@ -502,7 +560,7 @@ Mnemonic: I<b>oundary. =head2 Misc Here we document the backslash sequences that don't fall in one of the -categories above. They are: +categories above. These are: =over 4 @@ -510,46 +568,49 @@ categories above. They are: C<\C> always matches a single octet, even if the source string is encoded in UTF-8 format, and the character to be matched is a multi-octet character. -C<\C> was introduced in perl 5.6. +C<\C> was introduced in perl 5.6. This is very dangerous, because it violates +the logical character abstraction and can cause UTF-8 sequences to become malformed. Mnemonic: oI<C>tet. =item \K -This is new in perl 5.10.0. Anything that is matched left of C<\K> is -not included in C<$&> - and will not be replaced if the pattern is -used in a substitution. This will allow you to write C<s/PAT1 \K PAT2/REPL/x> +This appeared in perl 5.10.0. Anything matched left of C<\K> is +not included in C<$&>, and will not be replaced if the pattern is +used in a substitution. This lets you write C<s/PAT1 \K PAT2/REPL/x> instead of C<s/(PAT1) PAT2/${1}REPL/x> or C<s/(?<=PAT1) PAT2/REPL/x>. Mnemonic: I<K>eep. =item \N -This is a new experimental feature in perl 5.12.0. It matches any character -that is not a newline. It is a short-hand for writing C<[^\n]>, and is +This is an experimental feature new to perl 5.12.0. It matches any character +that is B<not> a newline. It is a short-hand for writing C<[^\n]>, and is identical to the C<.> metasymbol, except under the C</s> flag, which changes the meaning of C<.>, but not C<\N>. Note that C<\N{...}> can mean a -L<named or numbered character|/Named or numbered characters>. +L<named or numbered character +|/Named or numbered characters and character sequences>. Mnemonic: Complement of I<\n>. =item \R X<\R> -C<\R> matches a I<generic newline>, that is, anything that is considered -a newline by Unicode. This includes all characters matched by C<\v> -(vertical whitespace), and the multi character sequence C<"\x0D\x0A"> -(carriage return followed by a line feed, aka the network newline, or -the newline used in Windows text files). C<\R> is equivalent to -C<< (?>\x0D\x0A)|\v) >>. Since C<\R> can match a sequence of more than one -character, it cannot be put inside a bracketed character class; C</[\R]/> is an -error; use C<\v> instead. C<\R> was introduced in perl 5.10.0. +C<\R> matches a I<generic newline>; that is, anything considered a +linebreak sequence by Unicode. This includes all characters matched by +C<\v> (vertical whitespace), and the multi character sequence C<"\x0D\x0A"> +(carriage return followed by a line feed, sometimes called the network +newline; it's the end of line sequence used in Microsoft text files opened +in binary mode). C<\R> is equivalent to C<< (?>\x0D\x0A)|\v) >>. Since +C<\R> can match a sequence of more than one character, it cannot be put +inside a bracketed character class; C</[\R]/> is an error; use C<\v> +instead. C<\R> was introduced in perl 5.10.0. Mnemonic: none really. C<\R> was picked because PCRE already uses C<\R>, and more importantly because Unicode recommends such a regular expression -metacharacter, and suggests C<\R> as the notation. +metacharacter, and suggests C<\R> as its notation. =item \X X<\X> @@ -569,15 +630,15 @@ Mnemonic: eI<X>tended Unicode character. =head4 Examples - "\x{256}" =~ /^\C\C$/; # Match as chr (256) takes 2 octets in UTF-8. + "\x{256}" =~ /^\C\C$/; # Match as chr (0x256) takes 2 octets in UTF-8. - $str =~ s/foo\Kbar/baz/g; # Change any 'bar' following a 'foo' to 'baz'. - $str =~ s/(.)\K\1//g; # Delete duplicated characters. + $str =~ s/foo\Kbar/baz/g; # Change any 'bar' following a 'foo' to 'baz' + $str =~ s/(.)\K\g1//g; # Delete duplicated characters. "\n" =~ /^\R$/; # Match, \n is a generic newline. "\r" =~ /^\R$/; # Match, \r is a generic newline. "\r\n" =~ /^\R$/; # Match, \r\n is a generic newline. - "P\x{0307}" =~ /^\X$/ # \X matches a P with a dot above. + "P\x{307}" =~ /^\X$/ # \X matches a P with a dot above. =cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlrecharclass.pod b/Master/tlpkg/tlperl/lib/pods/perlrecharclass.pod index a9b5ea37c74..b7526b45fae 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlrecharclass.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlrecharclass.pod @@ -44,7 +44,7 @@ Here are some examples: "ab" =~ /^.$/ # No match (dot matches one character) =head2 Backslash sequences -X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\p> X<\P> +X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\p> X<\P> X<\N> X<\v> X<\V> X<\h> X<\H> X<word> X<whitespace> @@ -74,57 +74,104 @@ character classes, see L<perlrebackslash>.) =head3 Digits -C<\d> matches a single character that is considered to be a decimal I<digit>. -What is considered a decimal digit depends on the internal encoding of the -source string and the locale that is in effect. If the source string is in -UTF-8 format, C<\d> not only matches the digits '0' - '9', but also Arabic, -Devanagari and digits from other languages. Otherwise, if there is a locale in -effect, it will match whatever characters the locale considers decimal digits. -Without a locale, C<\d> matches just the digits '0' to '9'. -See L</Locale, EBCDIC, Unicode and UTF-8>. - -Unicode digits may cause some confusion, and some security issues. In UTF-8 -strings, C<\d> matches the same characters matched by -C<\p{General_Category=Decimal_Number}>, or synonymously, -C<\p{General_Category=Digit}>. Starting with Unicode version 4.1, this is the -same set of characters matched by C<\p{Numeric_Type=Decimal}>. - +C<\d> matches a single character considered to be a decimal I<digit>. +If the C</a> modifier in effect, it matches [0-9]. Otherwise, it +matches anything that is matched by C<\p{Digit}>, which includes [0-9]. +(An unlikely possible exception is that under locale matching rules, the +current locale might not have [0-9] matched by C<\d>, and/or might match +other characters whose code point is less than 256. Such a locale +definition would be in violation of the C language standard, but Perl +doesn't currently assume anything in regard to this.) + +What this means is that unless the C</a> modifier is in effect C<\d> not +only matches the digits '0' - '9', but also Arabic, Devanagari, and +digits from other languages. This may cause some confusion, and some +security issues. + +Some digits that C<\d> matches look like some of the [0-9] ones, but +have different values. For example, BENGALI DIGIT FOUR (U+09EA) looks +very much like an ASCII DIGIT EIGHT (U+0038). An application that +is expecting only the ASCII digits might be misled, or if the match is +C<\d+>, the matched string might contain a mixture of digits from +different writing systems that look like they signify a number different +than they actually do. L<Unicode::UCD/num()> can be used to safely +calculate the value, returning C<undef> if the input string contains +such a mixture. + +What C<\p{Digit}> means (and hence C<\d> except under the C</a> +modifier) is C<\p{General_Category=Decimal_Number}>, or synonymously, +C<\p{General_Category=Digit}>. Starting with Unicode version 4.1, this +is the same set of characters matched by C<\p{Numeric_Type=Decimal}>. But Unicode also has a different property with a similar name, C<\p{Numeric_Type=Digit}>, which matches a completely different set of -characters. These characters are things such as subscripts. - -The design intent is for C<\d> to match all the digits (and no other characters) -that can be used with "normal" big-endian positional decimal syntax, whereby a -sequence of such digits {N0, N1, N2, ...Nn} has the numeric value (...(N0 * 10 -+ N1) * 10 + N2) * 10 ... + Nn). In Unicode 5.2, the Tamil digits (U+0BE6 - -U+0BEF) can also legally be used in old-style Tamil numbers in which they would -appear no more than one in a row, separated by characters that mean "times 10", -"times 100", etc. (See L<http://www.unicode.org/notes/tn21>.) +characters. These characters are things such as C<CIRCLED DIGIT ONE> +or subscripts, or are from writing systems that lack all ten digits. -Some of the non-European digits that C<\d> matches look like European ones, but -have different values. For example, BENGALI DIGIT FOUR (U+09A) looks very much -like an ASCII DIGIT EIGHT (U+0038). +The design intent is for C<\d> to exactly match the set of characters +that can safely be used with "normal" big-endian positional decimal +syntax, where, for example 123 means one 'hundred', plus two 'tens', +plus three 'ones'. This positional notation does not necessarily apply +to characters that match the other type of "digit", +C<\p{Numeric_Type=Digit}>, and so C<\d> doesn't match them. -It may be useful for security purposes for an application to require that all -digits in a row be from the same script. See L<Unicode::UCD/charscript()>. +In Unicode 5.2, the Tamil digits (U+0BE6 - U+0BEF) can also legally be +used in old-style Tamil numbers in which they would appear no more than +one in a row, separated by characters that mean "times 10", "times 100", +etc. (See L<http://www.unicode.org/notes/tn21>.) -Any character that isn't matched by C<\d> will be matched by C<\D>. +Any character not matched by C<\d> is matched by C<\D>. =head3 Word characters A C<\w> matches a single alphanumeric character (an alphabetic character, or a -decimal digit) or an underscore (C<_>), not a whole word. To match a whole -word, use C<\w+>. This isn't the same thing as matching an English word, but -is the same as a string of Perl-identifier characters. What is considered a -word character depends on the internal -encoding of the string and the locale or EBCDIC code page that is in effect. If -it's in UTF-8 format, C<\w> matches those characters that are considered word -characters in the Unicode database. That is, it not only matches ASCII letters, -but also Thai letters, Greek letters, etc. If the source string isn't in UTF-8 -format, C<\w> matches those characters that are considered word characters by -the current locale or EBCDIC code page. Without a locale or EBCDIC code page, -C<\w> matches the ASCII letters, digits and the underscore. -See L</Locale, EBCDIC, Unicode and UTF-8>. +decimal digit) or a connecting punctuation character, such as an +underscore ("_"). It does not match a whole word. To match a whole +word, use C<\w+>. This isn't the same thing as matching an English word, but +in the ASCII range it is the same as a string of Perl-identifier +characters. + +=over + +=item If the C</a> modifier is in effect ... + +C<\w> matches the 63 characters [a-zA-Z0-9_]. + +=item otherwise ... + +=over + +=item For code points above 255 ... + +C<\w> matches the same as C<\p{Word}> matches in this range. That is, +it matches Thai letters, Greek letters, etc. This includes connector +punctuation (like the underscore) which connect two words together, or +diacritics, such as a C<COMBINING TILDE> and the modifier letters, which +are generally used to add auxiliary markings to letters. + +=item For code points below 256 ... + +=over + +=item if locale rules are in effect ... + +C<\w> matches the platform's native underscore character plus whatever +the locale considers to be alphanumeric. + +=item if Unicode rules are in effect or if on an EBCDIC platform ... + +C<\w> matches exactly what C<\p{Word}> matches. + +=item otherwise ... + +C<\w> matches [a-zA-Z0-9_]. + +=back + +=back + +=back + +Which rules apply are determined as described in L<perlre/Which character set modifier is in effect?>. There are a number of security issues with the full Unicode list of word characters. See L<http://unicode.org/reports/tr36>. @@ -134,36 +181,68 @@ language identifiers beyond the ASCII range, you may wish to instead use the more customized Unicode properties, "ID_Start", ID_Continue", "XID_Start", and "XID_Continue". See L<http://unicode.org/reports/tr31>. -Any character that isn't matched by C<\w> will be matched by C<\W>. +Any character not matched by C<\w> is matched by C<\W>. =head3 Whitespace -C<\s> matches any single character that is considered whitespace. The exact -set of characters matched by C<\s> depends on whether the source string is in -UTF-8 format and the locale or EBCDIC code page that is in effect. If it's in -UTF-8 format, C<\s> matches what is considered whitespace in the Unicode -database; the complete list is in the table below. Otherwise, if there is a -locale or EBCDIC code page in effect, C<\s> matches whatever is considered -whitespace by the current locale or EBCDIC code page. Without a locale or -EBCDIC code page, C<\s> matches the horizontal tab (C<\t>), the newline -(C<\n>), the form feed (C<\f>), the carriage return (C<\r>), and the space. -(Note that it doesn't match the vertical tab, C<\cK>.) Perhaps the most notable -possible surprise is that C<\s> matches a non-breaking space only if the -non-breaking space is in a UTF-8 encoded string or the locale or EBCDIC code -page that is in effect has that character. -See L</Locale, EBCDIC, Unicode and UTF-8>. - -Any character that isn't matched by C<\s> will be matched by C<\S>. - -C<\h> will match any character that is considered horizontal whitespace; -this includes the space and the tab characters and a number other characters, -all of which are listed in the table below. C<\H> will match any character -that is not considered horizontal whitespace. - -C<\v> will match any character that is considered vertical whitespace; -this includes the carriage return and line feed characters (newline) plus several -other characters, all listed in the table below. -C<\V> will match any character that is not considered vertical whitespace. +C<\s> matches any single character considered whitespace. + +=over + +=item If the C</a> modifier is in effect ... + +C<\s> matches the 5 characters [\t\n\f\r ]; that is, the horizontal tab, +the newline, the form feed, the carriage return, and the space. (Note +that it doesn't match the vertical tab, C<\cK> on ASCII platforms.) + +=item otherwise ... + +=over + +=item For code points above 255 ... + +C<\s> matches exactly the code points above 255 shown with an "s" column +in the table below. + +=item For code points below 256 ... + +=over + +=item if locale rules are in effect ... + +C<\s> matches whatever the locale considers to be whitespace. Note that +this is likely to include the vertical space, unlike non-locale C<\s> +matching. + +=item if Unicode rules are in effect or if on an EBCDIC platform ... + +C<\s> matches exactly the characters shown with an "s" column in the +table below. + +=item otherwise ... + +C<\s> matches [\t\n\f\r ]. +Note that this list doesn't include the non-breaking space. + +=back + +=back + +=back + +Which rules apply are determined as described in L<perlre/Which character set modifier is in effect?>. + +Any character not matched by C<\s> is matched by C<\S>. + +C<\h> matches any character considered horizontal whitespace; +this includes the space and tab characters and several others +listed in the table below. C<\H> matches any character +not considered horizontal whitespace. + +C<\v> matches any character considered vertical whitespace; +this includes the carriage return and line feed characters (newline) +plus several other characters, all listed in the table below. +C<\V> matches any character not considered vertical whitespace. C<\R> matches anything that can be considered a newline under Unicode rules. It's not a character class, as it can match a multi-character @@ -171,22 +250,16 @@ sequence. Therefore, it cannot be used inside a bracketed character class; use C<\v> instead (vertical whitespace). Details are discussed in L<perlrebackslash>. -Note that unlike C<\s>, C<\d> and C<\w>, C<\h> and C<\v> always match -the same characters, regardless whether the source string is in UTF-8 -format or not. The set of characters they match is also not influenced -by locale nor EBCDIC code page. +Note that unlike C<\s> (and C<\d> and C<\w>), C<\h> and C<\v> always match +the same characters, without regard to other factors, such as whether the +source string is in UTF-8 format. -One might think that C<\s> is equivalent to C<[\h\v]>. This is not true. The -vertical tab (C<"\x0b">) is not matched by C<\s>, it is however considered -vertical whitespace. Furthermore, if the source string is not in UTF-8 format, -and any locale or EBCDIC code page that is in effect doesn't include them, the -next line (ASCII-platform C<"\x85">) and the no-break space (ASCII-platform -C<"\xA0">) characters are not matched by C<\s>, but are by C<\v> and C<\h> -respectively. If the source string is in UTF-8 format, both the next line and -the no-break space are matched by C<\s>. +One might think that C<\s> is equivalent to C<[\h\v]>. This is not true. +For example, the vertical tab (C<"\x0b">) is not matched by C<\s>, it is +however considered vertical whitespace. The following table is a complete listing of characters matched by -C<\s>, C<\h> and C<\v> as of Unicode 5.2. +C<\s>, C<\h> and C<\v> as of Unicode 6.0. The first column gives the code point of the character (in hex format), the second column gives the (Unicode) name. The third column indicates @@ -224,18 +297,15 @@ page is in effect that changes the C<\s> matching). =item [1] -NEXT LINE and NO-BREAK SPACE only match C<\s> if the source string is in -UTF-8 format, or the locale or EBCDIC code page that is in effect includes them. +NEXT LINE and NO-BREAK SPACE may or may not match C<\s> depending +on the rules in effect. See +L<the beginning of this section|/Whitespace>. =back -It is worth noting that C<\d>, C<\w>, etc, match single characters, not -complete numbers or words. To match a number (that consists of integers), -use C<\d+>; to match a word, use C<\w+>. - =head3 \N -C<\N> is new in 5.12, and is experimental. It, like the dot, will match any +C<\N> is new in 5.12, and is experimental. It, like the dot, matches any character that is not a newline. The difference is that C<\N> is not influenced by the I<single line> regular expression modifier (see L</The dot> above). Note that the form C<\N{...}> may mean something completely different. When the @@ -245,7 +315,7 @@ non-newlines; C<\N{5,}> means to match 5 or more non-newlines. But if C<{...}> is not a legal quantifier, it is presumed to be a named character. See L<charnames> for those. For example, none of C<\N{COLON}>, C<\N{4F}>, and C<\N{F4}> contain legal quantifiers, so Perl will try to find characters whose -names are, respectively, C<COLON>, C<4F>, and C<F4>. +names are respectively C<COLON>, C<4F>, and C<F4>. =head3 Unicode Properties @@ -254,7 +324,7 @@ Unicode properties. One letter property names can be used in the C<\pP> form, with the property name following the C<\p>, otherwise, braces are required. When using braces, there is a single form, which is just the property name enclosed in the braces, and a compound form which looks like C<\p{name=value}>, -which means to match if the property "name" for the character has the particular +which means to match if the property "name" for the character has that particular "value". For instance, a match for a number can be written as C</\pN/> or as C</\p{Number}/>, or as C</\p{Number=True}/>. @@ -266,13 +336,37 @@ C</\pLl/> is valid, but means something different. It matches a two character string: a letter (Unicode property C<\pL>), followed by a lowercase C<l>. -For more details, see L<perlunicode/Unicode Character Properties>; for a +If neither the C</a> modifier nor locale rules are in effect, the use of +a Unicode property will force the regular expression into using Unicode +rules. + +Note that almost all properties are immune to case-insensitive matching. +That is, adding a C</i> regular expression modifier does not change what +they match. There are two sets that are affected. The first set is +C<Uppercase_Letter>, +C<Lowercase_Letter>, +and C<Titlecase_Letter>, +all of which match C<Cased_Letter> under C</i> matching. +The second set is +C<Uppercase>, +C<Lowercase>, +and C<Titlecase>, +all of which match C<Cased> under C</i> matching. +(The difference between these sets is that some things, such as Roman +Numerals, come in both upper and lower case so they are C<Cased>, but +aren't considered to be letters, so they aren't C<Cased_Letter>s. They're +actually C<Letter_Number>s.) +This set also includes its subsets C<PosixUpper> and C<PosixLower>, both +of which under C</i> matching match C<PosixAlpha>. + +For more details on Unicode properties, see L<perlunicode/Unicode +Character Properties>; for a complete list of possible properties, see -L<perluniprops/Properties accessible through \p{} and \P{}>. +L<perluniprops/Properties accessible through \p{} and \P{}>, +which notes all forms that have C</i> differences. It is also possible to define your own properties. This is discussed in L<perlunicode/User-Defined Character Properties>. - =head4 Examples "a" =~ /\w/ # Match, "a" is a 'word' character. @@ -296,6 +390,10 @@ L<perlunicode/User-Defined Character Properties>. # Thai Unicode class. "a" =~ /\P{Lao}/ # Match, as "a" is not a Laotian character. +It is worth emphasizing that C<\d>, C<\w>, etc, match single characters, not +complete numbers or words. To match a number (that consists of digits), +use C<\d+>; to match a word, use C<\w+>. But be aware of the security +considerations in doing so, as mentioned above. =head2 Bracketed Character Classes @@ -303,10 +401,10 @@ The third form of character class you can use in Perl regular expressions is the bracketed character class. In its simplest form, it lists the characters that may be matched, surrounded by square brackets, like this: C<[aeiou]>. This matches one of C<a>, C<e>, C<i>, C<o> or C<u>. Like the other -character classes, exactly one character will be matched. To match +character classes, exactly one character is matched.* To match a longer string consisting of characters mentioned in the character class, follow the character class with a L<quantifier|perlre/Quantifiers>. For -instance, C<[aeiou]+> matches a string of one or more lowercase English vowels. +instance, C<[aeiou]+> matches one or more lowercase English vowels. Repeating a character in a character class has no effect; it's considered to be in the set only once. @@ -319,6 +417,19 @@ Examples: # a single character. "ae" =~ /^[aeiou]+$/ # Match, due to the quantifier. + ------- + +* There is an exception to a bracketed character class matching only a +single character. When the class is to match caselessely under C</i> +matching rules, and a character inside the class matches a +multiple-character sequence caselessly under Unicode rules, the class +(when not L<inverted|/Negation>) will also match that sequence. For +example, Unicode says that the letter C<LATIN SMALL LETTER SHARP S> +should match the sequence C<ss> under C</i> rules. Thus, + + 'ss' =~ /\A\N{LATIN SMALL LETTER SHARP S}\z/i # Matches + 'ss' =~ /\A[aeioust\N{LATIN SMALL LETTER SHARP S}]\z/i # Matches + =head3 Special Characters Inside a Bracketed Character Class Most characters that are meta characters in regular expressions (that @@ -346,13 +457,15 @@ C<\e>, C<\f>, C<\n>, C<\N{I<NAME>}>, -C<\N{U+I<wide hex char>}>, +C<\N{U+I<hex char>}>, C<\r>, C<\t>, and C<\x> -are also special and have the same meanings as they do outside a bracketed character -class. +are also special and have the same meanings as they do outside a +bracketed character class. (However, inside a bracketed character +class, if C<\N{I<NAME>}> expands to a sequence of characters, only the first +one in the sequence is used, with a warning.) Also, a backslash followed by two or three octal digits is considered an octal number. @@ -365,6 +478,7 @@ A C<]> is normally either the end of a POSIX character class (see L</POSIX Character Classes> below), or it signals the end of the bracketed character class. If you want to include a C<]> in the set of characters, you must generally escape it. + However, if the C<]> is the I<first> (or the second if the first character is a caret) character of a bracketed character class, it does not denote the end of the class (as you cannot have an empty class) @@ -385,26 +499,26 @@ Examples: =head3 Character Ranges It is not uncommon to want to match a range of characters. Luckily, instead -of listing all the characters in the range, one may use the hyphen (C<->). +of listing all characters in the range, one may use the hyphen (C<->). If inside a bracketed character class you have two characters separated -by a hyphen, it's treated as if all the characters between the two are in +by a hyphen, it's treated as if all characters between the two were in the class. For instance, C<[0-9]> matches any ASCII digit, and C<[a-m]> -matches any lowercase letter from the first half of the ASCII alphabet. +matches any lowercase letter from the first half of the old ASCII alphabet. Note that the two characters on either side of the hyphen are not -necessary both letters or both digits. Any character is possible, +necessarily both letters or both digits. Any character is possible, although not advisable. C<['-?]> contains a range of characters, but -most people will not know which characters that will be. Furthermore, +most people will not know which characters that means. Furthermore, such ranges may lead to portability problems if the code has to run on a platform that uses a different character set, such as EBCDIC. If a hyphen in a character class cannot syntactically be part of a range, for instance because it is the first or the last character of the character class, -or if it immediately follows a range, the hyphen isn't special, and will be -considered a character that is to be matched literally. You have to escape the -hyphen with a backslash if you want to have a hyphen in your set of characters -to be matched, and its position in the class is such that it could be -considered part of a range. +or if it immediately follows a range, the hyphen isn't special, and so is +considered a character to be matched literally. If you want a hyphen in +your set of characters to be matched and its position in the class is such +that it could be considered part of a range, you must escape that hyphen +with a backslash. Examples: @@ -422,13 +536,27 @@ Examples: It is also possible to instead list the characters you do not want to match. You can do so by using a caret (C<^>) as the first character in the -character class. For instance, C<[^a-z]> matches a character that is not a -lowercase ASCII letter. +character class. For instance, C<[^a-z]> matches any character that is not a +lowercase ASCII letter, which therefore includes almost a hundred thousand +Unicode letters. The class is said to be "negated" or "inverted". This syntax make the caret a special character inside a bracketed character class, but only if it is the first character of the class. So if you want -to have the caret as one of the characters you want to match, you either -have to escape the caret, or not list it first. +the caret as one of the characters to match, either escape the caret or +else not list it first. + +In inverted bracketed character classes, Perl ignores the Unicode rules +that normally say that a given character matches a sequence of multiple +characters under caseless C</i> matching, which otherwise could be +highly confusing: + + "ss" =~ /^[^\xDF]+$/ui; + +This should match any sequences of characters that aren't C<\xDF> nor +what C<\xDF> matches under C</i>. C<"s"> isn't C<\xDF>, but Unicode +says that C<"ss"> is what C<\xDF> matches under C</i>. So which one +"wins"? Do you fail the match because the string has C<ss> or accept it +because it has an C<s> followed by another C<s>? Examples: @@ -440,13 +568,13 @@ Examples: =head3 Backslash Sequences You can put any backslash sequence character class (with the exception of -C<\N>) inside a bracketed character class, and it will act just -as if you put all the characters matched by the backslash sequence inside the -character class. For instance, C<[a-f\d]> will match any decimal digit, or any +C<\N> and C<\R>) inside a bracketed character class, and it will act just +as if you had put all characters matched by the backslash sequence inside the +character class. For instance, C<[a-f\d]> matches any decimal digit, or any of the lowercase letters between 'a' and 'f' inclusive. C<\N> within a bracketed character class must be of the forms C<\N{I<name>}> -or C<\N{U+I<wide hex char>}>, and NOT be the form that matches non-newlines, +or C<\N{U+I<hex char>}>, and NOT be the form that matches non-newlines, for the same reason that a dot C<.> inside a bracketed character class loses its special meaning: it matches nearly anything, which generally isn't what you want to happen. @@ -472,8 +600,7 @@ X<lower> X<print> X<punct> X<space> X<upper> X<word> X<xdigit> POSIX character classes have the form C<[:class:]>, where I<class> is name, and the C<[:> and C<:]> delimiters. POSIX character classes only appear I<inside> bracketed character classes, and are a convenient and descriptive -way of listing a group of characters, though they currently suffer from -portability issues (see below and L<Locale, EBCDIC, Unicode and UTF-8>). +way of listing a group of characters. Be careful about the syntax, @@ -485,8 +612,8 @@ Be careful about the syntax, The latter pattern would be a character class consisting of a colon, and the letters C<a>, C<l>, C<p> and C<h>. -POSIX character classes can be part of a larger bracketed character class. For -example, +POSIX character classes can be part of a larger bracketed character class. +For example, [01[:alpha:]%] @@ -495,7 +622,7 @@ is valid and matches '0', '1', any alphabetic character, and the percent sign. Perl recognizes the following POSIX character classes: alpha Any alphabetical character ("[A-Za-z]"). - alnum Any alphanumerical character. ("[A-Za-z0-9]") + alnum Any alphanumeric character. ("[A-Za-z0-9]") ascii Any character in the ASCII character set. blank A GNU extension, equal to a space or a horizontal tab ("\t"). cntrl Any control character. See Note [2] below. @@ -515,57 +642,93 @@ derived from official Unicode properties.) The table below shows the relation between POSIX character classes and these counterparts. One counterpart, in the column labelled "ASCII-range Unicode" in -the table, will only match characters in the ASCII character set. +the table, matches only characters in the ASCII character set. The other counterpart, in the column labelled "Full-range Unicode", matches any appropriate characters in the full Unicode character set. For example, -C<\p{Alpha}> will match not just the ASCII alphabetic characters, but any -character in the entire Unicode character set that is considered to be -alphabetic. +C<\p{Alpha}> matches not just the ASCII alphabetic characters, but any +character in the entire Unicode character set considered alphabetic. +The column labelled "backslash sequence" is a (short) synonym for +the Full-range Unicode form. (Each of the counterparts has various synonyms as well. -L<perluniprops/Properties accessible through \p{} and \P{}> lists all the -synonyms, plus all the characters matched by each of the ASCII-range -properties. For example C<\p{AHex}> is a synonym for C<\p{ASCII_Hex_Digit}>, +L<perluniprops/Properties accessible through \p{} and \P{}> lists all +synonyms, plus all characters matched by each ASCII-range property. +For example, C<\p{AHex}> is a synonym for C<\p{ASCII_Hex_Digit}>, and any C<\p> property name can be prefixed with "Is" such as C<\p{IsAlpha}>.) -Both the C<\p> forms are unaffected by any locale that is in effect, or whether -the string is in UTF-8 format or not, or whether the platform is EBCDIC or not. -In contrast, the POSIX character classes are affected. If the source string is -in UTF-8 format, the POSIX classes (with the exception of C<[[:punct:]]>, see -Note [5] below) behave like their "Full-range" Unicode counterparts. If the -source string is not in UTF-8 format, and no locale is in effect, and the -platform is not EBCDIC, all the POSIX classes behave like their ASCII-range -counterparts. Otherwise, they behave based on the rules of the locale or -EBCDIC code page. - -It is proposed to change this behavior in a future release of Perl so that the -the UTF8ness of the source string will be irrelevant to the behavior of the -POSIX character classes. This means they will always behave in strict -accordance with the official POSIX standard. That is, if either locale or -EBCDIC code page is present, they will behave in accordance with those; if -absent, the classes will match only their ASCII-range counterparts. If you -disagree with this proposal, send email to C<perl5-porters@perl.org>. - - [[:...:]] ASCII-range Full-range backslash Note - Unicode Unicode sequence +Both the C<\p> counterparts always assume Unicode rules are in effect. +On ASCII platforms, this means they assume that the code points from 128 +to 255 are Latin-1, and that means that using them under locale rules is +unwise unless the locale is guaranteed to be Latin-1 or UTF-8. In contrast, the +POSIX character classes are useful under locale rules. They are +affected by the actual rules in effect, as follows: + +=over + +=item If the C</a> modifier, is in effect ... + +Each of the POSIX classes matches exactly the same as their ASCII-range +counterparts. + +=item otherwise ... + +=over + +=item For code points above 255 ... + +The POSIX class matches the same as its Full-range counterpart. + +=item For code points below 256 ... + +=over + +=item if locale rules are in effect ... + +The POSIX class matches according to the locale. + +=item if Unicode rules are in effect or if on an EBCDIC platform ... + +The POSIX class matches the same as the Full-range counterpart. + +=item otherwise ... + +The POSIX class matches the same as the ASCII range counterpart. + +=back + +=back + +=back + +Which rules apply are determined as described in +L<perlre/Which character set modifier is in effect?>. + +It is proposed to change this behavior in a future release of Perl so that +whether or not Unicode rules are in effect would not change the +behavior: Outside of locale or an EBCDIC code page, the POSIX classes +would behave like their ASCII-range counterparts. If you wish to +comment on this proposal, send email to C<perl5-porters@perl.org>. + + [[:...:]] ASCII-range Full-range backslash Note + Unicode Unicode sequence ----------------------------------------------------- - alpha \p{PosixAlpha} \p{Alpha} - alnum \p{PosixAlnum} \p{Alnum} - ascii \p{ASCII} - blank \p{PosixBlank} \p{Blank} = [1] - \p{HorizSpace} \h [1] - cntrl \p{PosixCntrl} \p{Cntrl} [2] - digit \p{PosixDigit} \p{Digit} \d - graph \p{PosixGraph} \p{Graph} [3] - lower \p{PosixLower} \p{Lower} - print \p{PosixPrint} \p{Print} [4] - punct \p{PosixPunct} \p{Punct} [5] - \p{PerlSpace} \p{SpacePerl} \s [6] - space \p{PosixSpace} \p{Space} [6] - upper \p{PosixUpper} \p{Upper} - word \p{PerlWord} \p{Word} \w - xdigit \p{ASCII_Hex_Digit} \p{XDigit} + alpha \p{PosixAlpha} \p{XPosixAlpha} + alnum \p{PosixAlnum} \p{XPosixAlnum} + ascii \p{ASCII} + blank \p{PosixBlank} \p{XPosixBlank} \h [1] + or \p{HorizSpace} [1] + cntrl \p{PosixCntrl} \p{XPosixCntrl} [2] + digit \p{PosixDigit} \p{XPosixDigit} \d + graph \p{PosixGraph} \p{XPosixGraph} [3] + lower \p{PosixLower} \p{XPosixLower} + print \p{PosixPrint} \p{XPosixPrint} [4] + punct \p{PosixPunct} \p{XPosixPunct} [5] + \p{PerlSpace} \p{XPerlSpace} \s [6] + space \p{PosixSpace} \p{XPosixSpace} [6] + upper \p{PosixUpper} \p{XPosixUpper} + word \p{PosixWord} \p{XPosixWord} \w + xdigit \p{PosixXDigit} \p{XPosixXDigit} =over 4 @@ -576,51 +739,59 @@ C<\p{Blank}> and C<\p{HorizSpace}> are synonyms. =item [2] Control characters don't produce output as such, but instead usually control -the terminal somehow: for example newline and backspace are control characters. -In the ASCII range, characters whose ordinals are between 0 and 31 inclusive, +the terminal somehow: for example, newline and backspace are control characters. +In the ASCII range, characters whose code points are between 0 and 31 inclusive, plus 127 (C<DEL>) are control characters. On EBCDIC platforms, it is likely that the code page will define C<[[:cntrl:]]> to be the EBCDIC equivalents of the ASCII controls, plus the controls -that in Unicode have ordinals from 128 through 159. +that in Unicode have code pointss from 128 through 159. =item [3] Any character that is I<graphical>, that is, visible. This class consists -of all the alphanumerical characters and all punctuation characters. +of all alphanumeric characters and all punctuation characters. =item [4] -All printable characters, which is the set of all the graphical characters -plus whitespace characters that are not also controls. +All printable characters, which is the set of all graphical characters +plus those whitespace characters which are not also controls. -=item [5] (punct) +=item [5] -C<\p{PosixPunct}> and C<[[:punct:]]> in the ASCII range match all the +C<\p{PosixPunct}> and C<[[:punct:]]> in the ASCII range match all non-controls, non-alphanumeric, non-space characters: C<[-!"#$%&'()*+,./:;<=E<gt>?@[\\\]^_`{|}~]> (although if a locale is in effect, it could alter the behavior of C<[[:punct:]]>). -C<\p{Punct}> matches a somewhat different set in the ASCII range, namely +The similarly named property, C<\p{Punct}>, matches a somewhat different +set in the ASCII range, namely C<[-!"#%&'()*,./:;?@[\\\]_{}]>. That is, it is missing C<[$+E<lt>=E<gt>^`|~]>. This is because Unicode splits what POSIX considers to be punctuation into two categories, Punctuation and Symbols. -When the matching string is in UTF-8 format, C<[[:punct:]]> matches what it -matches in the ASCII range, plus what C<\p{Punct}> matches. This is different -than strictly matching according to C<\p{Punct}>. Another way to say it is that -for a UTF-8 string, C<[[:punct:]]> matches all the characters that Unicode -considers to be punctuation, plus all the ASCII-range characters that Unicode -considers to be symbols. +C<\p{XPosixPunct}> and (in Unicode mode) C<[[:punct:]]>, match what +C<\p{PosixPunct}> matches in the ASCII range, plus what C<\p{Punct}> +matches. This is different than strictly matching according to +C<\p{Punct}>. Another way to say it is that +if Unicode rules are in effect, C<[[:punct:]]> matches all characters +that Unicode considers punctuation, plus all ASCII-range characters that +Unicode considers symbols. =item [6] -C<\p{SpacePerl}> and C<\p{Space}> differ only in that C<\p{Space}> additionally +C<\p{SpacePerl}> and C<\p{Space}> differ only in that in non-locale +matching, C<\p{Space}> additionally matches the vertical tab, C<\cK>. Same for the two ASCII-only range forms. =back -=head4 Negation +There are various other synonyms that can be used for these besides +C<\p{HorizSpace}> and \C<\p{XPosixBlank}>. For example, +C<\p{PosixAlpha}> can be written as C<\p{Alpha}>. All are listed +in L<perluniprops/Properties accessible through \p{} and \P{}>. + +=head4 Negation of POSIX character classes X<character class, negation> A Perl extension to the POSIX character class is the ability to @@ -630,17 +801,19 @@ Some examples: POSIX ASCII-range Full-range backslash Unicode Unicode sequence ----------------------------------------------------- - [[:^digit:]] \P{PosixDigit} \P{Digit} \D - [[:^space:]] \P{PosixSpace} \P{Space} - \P{PerlSpace} \P{SpacePerl} \S - [[:^word:]] \P{PerlWord} \P{Word} \W + [[:^digit:]] \P{PosixDigit} \P{XPosixDigit} \D + [[:^space:]] \P{PosixSpace} \P{XPosixSpace} + \P{PerlSpace} \P{XPerlSpace} \S + [[:^word:]] \P{PerlWord} \P{XPosixWord} \W -=head4 [= =] and [. .] +The backslash sequence can mean either ASCII- or Full-range Unicode, +depending on various factors as described in L<perlre/Which character set modifier is in effect?>. -Perl will recognize the POSIX character classes C<[=class=]>, and -C<[.class.]>, but does not (yet?) support them. Use of -such a construct will lead to an error. +=head4 [= =] and [. .] +Perl recognizes the POSIX character classes C<[=class=]> and +C<[.class.]>, but does not (yet?) support them. Any attempt to use +either construct raises an exception. =head4 Examples @@ -656,44 +829,3 @@ such a construct will lead to an error. # hex digit. The result matches all # characters except the letters 'a' to 'f' and # 'A' to 'F'. - - -=head2 Locale, EBCDIC, Unicode and UTF-8 - -Some of the character classes have a somewhat different behaviour depending -on the internal encoding of the source string, and the locale that is -in effect, and if the program is running on an EBCDIC platform. - -C<\w>, C<\d>, C<\s> and the POSIX character classes (and their negations, -including C<\W>, C<\D>, C<\S>) suffer from this behaviour. (Since the backslash -sequences C<\b> and C<\B> are defined in terms of C<\w> and C<\W>, they also are -affected.) - -The rule is that if the source string is in UTF-8 format, the character -classes match according to the Unicode properties. If the source string -isn't, then the character classes match according to whatever locale or EBCDIC -code page is in effect. If there is no locale nor EBCDIC, they match the ASCII -defaults (0 to 9 for C<\d>; 52 letters, 10 digits and underscore for C<\w>; -etc.). - -This usually means that if you are matching against characters whose C<ord()> -values are between 128 and 255 inclusive, your character class may match -or not depending on the current locale or EBCDIC code page, and whether the -source string is in UTF-8 format. The string will be in UTF-8 format if it -contains characters whose C<ord()> value exceeds 255. But a string may be in -UTF-8 format without it having such characters. See L<perlunicode/The -"Unicode Bug">. - -For portability reasons, it may be better to not use C<\w>, C<\d>, C<\s> -or the POSIX character classes, and use the Unicode properties instead. - -=head4 Examples - - $str = "\xDF"; # $str is not in UTF-8 format. - $str =~ /^\w/; # No match, as $str isn't in UTF-8 format. - $str .= "\x{0e0b}"; # Now $str is in UTF-8 format. - $str =~ /^\w/; # Match! $str is now in UTF-8 format. - chop $str; - $str =~ /^\w/; # Still a match! $str remains in UTF-8 format. - -=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlrequick.pod b/Master/tlpkg/tlperl/lib/pods/perlrequick.pod index 4b5e19a0fb1..d543389d488 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlrequick.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlrequick.pod @@ -19,7 +19,7 @@ contains that word: "Hello World" =~ /World/; # matches In this statement, C<World> is a regex and the C<//> enclosing -C</World/> tells perl to search a string for a match. The operator +C</World/> tells Perl to search a string for a match. The operator C<=~> associates the string with the regex match and produces a true value if the regex matched, or false if the regex did not match. In our case, C<World> matches the second word in C<"Hello World">, so the @@ -58,7 +58,7 @@ statement to be true: "Hello World" =~ /o W/; # matches, ' ' is an ordinary char "Hello World" =~ /World /; # doesn't match, no ' ' at end -perl will always match at the earliest possible point in the string: +Perl will always match at the earliest possible point in the string: "Hello World" =~ /o/; # matches 'o' in 'Hello' "That hat is red" =~ /hat/; # matches 'hat' in 'That' @@ -88,7 +88,7 @@ e.g., C<\x1B>: "1000\t2000" =~ m(0\t2) # matches "cat" =~ /\143\x61\x74/ # matches in ASCII, but a weird way to spell cat -Regexes are treated mostly as double quoted strings, so variable +Regexes are treated mostly as double-quoted strings, so variable substitution works: $foo = 'house'; @@ -161,7 +161,9 @@ character, or the match fails. Then /[^0-9]/; # matches a non-numeric character /[a^]at/; # matches 'aat' or '^at'; here '^' is ordinary -Perl has several abbreviations for common character classes: +Perl has several abbreviations for common character classes. (These +definitions are those that Perl uses in ASCII mode with the C</a> modifier. +See L<perlrecharclass/Backslash sequences> for details.) =over 4 @@ -233,11 +235,11 @@ boundary. We can match different character strings with the B<alternation> metacharacter C<'|'>. To match C<dog> or C<cat>, we form the regex -C<dog|cat>. As before, perl will try to match the regex at the +C<dog|cat>. As before, Perl will try to match the regex at the earliest possible point in the string. At each character position, -perl will first try to match the first alternative, C<dog>. If -C<dog> doesn't match, perl will then try the next alternative, C<cat>. -If C<cat> doesn't match either, then the match fails and perl moves to +Perl will first try to match the first alternative, C<dog>. If +C<dog> doesn't match, Perl will then try the next alternative, C<cat>. +If C<cat> doesn't match either, then the match fails and Perl moves to the next position in the string. Some examples: "cats and dogs" =~ /cat|dog|bird/; # matches "cat" @@ -298,13 +300,13 @@ indicated below it: 1 2 34 Associated with the matching variables C<$1>, C<$2>, ... are -the B<backreferences> C<\1>, C<\2>, ... Backreferences are +the B<backreferences> C<\g1>, C<\g2>, ... Backreferences are matching variables that can be used I<inside> a regex: - /(\w\w\w)\s\1/; # find sequences like 'the the' in string + /(\w\w\w)\s\g1/; # find sequences like 'the the' in string -C<$1>, C<$2>, ... should only be used outside of a regex, and C<\1>, -C<\2>, ... only inside a regex. +C<$1>, C<$2>, ... should only be used outside of a regex, and C<\g1>, +C<\g2>, ... only inside a regex. =head2 Matching repetitions @@ -347,10 +349,10 @@ Here are some examples: /[a-z]+\s+\d*/; # match a lowercase word, at least some space, and # any number of digits - /(\w+)\s+\1/; # match doubled words of arbitrary length - $year =~ /\d{2,4}/; # make sure year is at least 2 but not more - # than 4 digits - $year =~ /\d{4}|\d{2}/; # better match; throw out 3 digit dates + /(\w+)\s+\g1/; # match doubled words of arbitrary length + $year =~ /^\d{2,4}$/; # make sure year is at least 2 but not more + # than 4 digits + $year =~ /^\d{4}$|^\d{2}$/; # better match; throw out 3 digit dates These quantifiers will try to match as much of the string as possible, while still allowing the regex to match. So we have @@ -368,22 +370,7 @@ no string left to it, so it matches 0 times. =head2 More matching There are a few more things you might want to know about matching -operators. In the code - - $pattern = 'Seuss'; - while (<>) { - print if /$pattern/; - } - -perl has to re-evaluate C<$pattern> each time through the loop. If -C<$pattern> won't be changing, use the C<//o> modifier, to only -perform variable substitutions once. If you don't want any -substitutions at all, use the special delimiter C<m''>: - - @pattern = ('Seuss'); - m/@pattern/; # matches 'Seuss' - m'@pattern'; # matches the literal string '@pattern' - +operators. The global modifier C<//g> allows the matching operator to match within a string as many times as possible. In scalar context, successive matches against a string will have C<//g> jump from match @@ -417,11 +404,11 @@ there are no groupings, a list of matches to the whole regex. So =head2 Search and replace Search and replace is performed using C<s/regex/replacement/modifiers>. -The C<replacement> is a Perl double quoted string that replaces in the +The C<replacement> is a Perl double-quoted string that replaces in the string whatever is matched with the C<regex>. The operator C<=~> is also used here to associate a string with C<s///>. If matching -against C<$_>, the S<C<$_ =~> > can be dropped. If there is a match, -C<s///> returns the number of substitutions made, otherwise it returns +against C<$_>, the S<C<$_ =~>> can be dropped. If there is a match, +C<s///> returns the number of substitutions made; otherwise it returns false. Here are a few examples: $x = "Time to feed the cat!"; @@ -440,6 +427,21 @@ of the regex in the string: $x = "I batted 4 for 4"; $x =~ s/4/four/g; # $x contains "I batted four for four" +The non-destructive modifier C<s///r> causes the result of the substitution +to be returned instead of modifying C<$_> (or whatever variable the +substitute was bound to with C<=~>): + + $x = "I like dogs."; + $y = $x =~ s/dogs/cats/r; + print "$x $y\n"; # prints "I like dogs. I like cats." + + $x = "Cats are great."; + print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~ s/Frogs/Hedgehogs/r, "\n"; + # prints "Hedgehogs are great." + + @foo = map { s/[a-z]/X/r } qw(a b c 1 2 3); + # @foo is now qw(X X X 1 2 3) + The evaluation modifier C<s///e> wraps an C<eval{...}> around the replacement string and the evaluated result is substituted for the matched substring. Some examples: @@ -454,7 +456,7 @@ matched substring. Some examples: The last example shows that C<s///> can use other delimiters, such as C<s!!!> and C<s{}{}>, and even C<s{}//>. If single quotes are used -C<s'''>, then the regex and replacement are treated as single quoted +C<s'''>, then the regex and replacement are treated as single-quoted strings. =head2 The split operator diff --git a/Master/tlpkg/tlperl/lib/pods/perlreref.pod b/Master/tlpkg/tlperl/lib/pods/perlreref.pod index ad970d2dce7..f5a79759296 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlreref.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlreref.pod @@ -21,7 +21,7 @@ false if the match succeeds, and true if it fails. $var !~ /foo/; -C<m/pattern/msixpogc> searches a string for a pattern match, +C<m/pattern/msixpogcdual> searches a string for a pattern match, applying the given options. m Multiline mode - ^ and $ match internal lines @@ -33,21 +33,28 @@ applying the given options. o compile pattern Once g Global - all occurrences c don't reset pos on failed matches when using /g + a restrict \d, \s, \w and [:posix:] to match ASCII only + aa (two a's) also /i matches exclude ASCII/non-ASCII + l match according to current locale + u match according to Unicode rules + d match according to native rules unless something indicates + Unicode If 'pattern' is an empty string, the last I<successfully> matched regex is used. Delimiters other than '/' may be used for both this operator and the following ones. The leading C<m> can be omitted if the delimiter is '/'. -C<qr/pattern/msixpo> lets you store a regex in a variable, +C<qr/pattern/msixpodual> lets you store a regex in a variable, or pass one around. Modifiers as for C<m//>, and are stored within the regex. -C<s/pattern/replacement/msixpogce> substitutes matches of +C<s/pattern/replacement/msixpogcedual> substitutes matches of 'pattern' with 'replacement'. Modifiers as for C<m//>, -with one addition: +with two additions: e Evaluate 'replacement' as an expression + r Return substitution and leave the original string untouched. 'e' may be specified multiple times. 'replacement' is interpreted as a double quoted string unless a single-quote (C<'>) is the delimiter. @@ -70,8 +77,8 @@ delimiters can be used. Must be reset with reset(). (...) Groups subexpressions for capturing to $1, $2... (?:...) Groups subexpressions without capturing (cluster) | Matches either the subexpression preceding or following it - \1, \2, \3 ... Matches the text from the Nth group \g1 or \g{1}, \g2 ... Matches the text from the Nth group + \1, \2, \3 ... Matches the text from the Nth group \g-1 or \g{-1}, \g-2 ... Matches the text from the Nth previous group \g{name} Named backreference \k<name> Named backreference @@ -93,7 +100,7 @@ These work as in normal strings. \x7f Char whose ordinal is the 2 hex digits, max \xFF \x{263a} Char whose ordinal is the hex number, unrestricted \cx Control-x - \N{name} A named Unicode character + \N{name} A named Unicode character or character sequence \N{U+263D} A Unicode character by hex ordinal \l Lowercase next character @@ -144,44 +151,40 @@ and L<perlunicode> for details. POSIX character classes and their Unicode and Perl equivalents: - ASCII- Full- - range range backslash - POSIX \p{...} \p{} sequence Description + ASCII- Full- + POSIX range range backslash + [[:...:]] \p{...} \p{...} sequence Description + ----------------------------------------------------------------------- - alnum PosixAlnum Alnum Alpha plus Digit - alpha PosixAlpha Alpha Alphabetic characters - ascii ASCII Any ASCII character - blank PosixBlank Blank \h Horizontal whitespace; - full-range also written - as \p{HorizSpace} (GNU - extension) - cntrl PosixCntrl Cntrl Control characters - digit PosixDigit Digit \d Decimal digits - graph PosixGraph Graph Alnum plus Punct - lower PosixLower Lower Lowercase characters - print PosixPrint Print Graph plus Print, but not - any Cntrls - punct PosixPunct Punct These aren't precisely - equivalent. See NOTE, - below. - space PosixSpace Space [\s\cK] Whitespace - PerlSpace SpacePerl \s Perl's whitespace - definition - upper PosixUpper Upper Uppercase characters - word PerlWord Word \w Alnum plus '_' (Perl - extension) - xdigit ASCII_Hex_Digit XDigit Hexadecimal digit, - ASCII-range is - [0-9A-Fa-f] - -NOTE on C<[[:punct:]]>, C<\p{PosixPunct}> and C<\p{Punct}>: -In the ASCII range, C<[[:punct:]]> and C<\p{PosixPunct}> match -C<[-!"#$%&'()*+,./:;<=E<gt>?@[\\\]^_`{|}~]> (although if a locale is in -effect, it could alter the behavior of C<[[:punct:]]>); and C<\p{Punct}> -matches C<[-!"#%&'()*,./:;?@[\\\]_{}]>. When matching a UTF-8 string, -C<[[:punct:]]> matches what it does in the ASCII range, plus what -C<\p{Punct}> matches. C<\p{Punct}> matches, anything that isn't a -control, an alphanumeric, a space, nor a symbol. + alnum PosixAlnum XPosixAlnum Alpha plus Digit + alpha PosixAlpha XPosixAlpha Alphabetic characters + ascii ASCII Any ASCII character + blank PosixBlank XPosixBlank \h Horizontal whitespace; + full-range also + written as + \p{HorizSpace} (GNU + extension) + cntrl PosixCntrl XPosixCntrl Control characters + digit PosixDigit XPosixDigit \d Decimal digits + graph PosixGraph XPosixGraph Alnum plus Punct + lower PosixLower XPosixLower Lowercase characters + print PosixPrint XPosixPrint Graph plus Print, but + not any Cntrls + punct PosixPunct XPosixPunct Punctuation and Symbols + in ASCII-range; just + punct outside it + space PosixSpace XPosixSpace [\s\cK] + PerlSpace XPerlSpace \s Perl's whitespace def'n + upper PosixUpper XPosixUpper Uppercase characters + word PerlWord XPosixWord \w Alnum + Unicode marks + + connectors, like '_' + (Perl extension) + xdigit ASCII_Hex_Digit XPosixDigit Hexadecimal digit, + ASCII-range is + [0-9A-Fa-f] + +Also, various synonyms like C<\p{Alpha}> for C<\p{XPosixAlpha}>; all listed +in L<perluniprops/Properties accessible through \p{} and \P{}> Within a character class: @@ -246,6 +249,10 @@ There is no quantifier C<{,n}>. That's interpreted as a literal string. (?P>name) Recurse into a named subpattern (python syntax) (?(cond)yes|no) (?(cond)yes) Conditional expression, where "cond" can be: + (?=pat) look-ahead + (?!pat) negative look-ahead + (?<=pat) look-behind + (?<!pat) negative look-behind (N) subpattern N has matched something (<name>) named subpattern has matched something ('name') named subpattern has matched something @@ -281,8 +288,8 @@ specify the C</p> (preserve) modifier on your regular expression. $^R Holds the result of the last (?{...}) expr @- Offsets of starts of groups. $-[0] holds start of whole match @+ Offsets of ends of groups. $+[0] holds end of whole match - %+ Named capture buffers - %- Named capture buffers, as array refs + %+ Named capture groups + %- Named capture groups, as array refs Captured groups are numbered according to their I<opening> paren. @@ -363,7 +370,7 @@ debugging. =item * -L<perldebug/"Debugging regular expressions"> +L<perldebug/"Debugging Regular Expressions"> =item * diff --git a/Master/tlpkg/tlperl/lib/pods/perlretut.pod b/Master/tlpkg/tlperl/lib/pods/perlretut.pod index 0ff743838c4..ea80594e605 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlretut.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlretut.pod @@ -41,7 +41,7 @@ you master the first part, you will have all the tools needed to solve about 98% of your needs. The second part of the tutorial is for those comfortable with the basics and hungry for more power tools. It discusses the more advanced regular expression operators and -introduces the latest cutting edge innovations in 5.6.0. +introduces the latest cutting-edge innovations. A note: to save time, 'regular expression' is often abbreviated as regexp or regex. Regexp is a more natural abbreviation than regex, but @@ -60,7 +60,7 @@ contains that word: "Hello World" =~ /World/; # matches What is this Perl statement all about? C<"Hello World"> is a simple -double quoted string. C<World> is the regular expression and the +double-quoted string. C<World> is the regular expression and the C<//> enclosing C</World/> tells Perl to search a string for a match. The operator C<=~> associates the string with the regexp match and produces a true value if the regexp matched, or false if the regexp @@ -176,7 +176,7 @@ In addition to the metacharacters, there are some ASCII characters which don't have printable character equivalents and are instead represented by I<escape sequences>. Common examples are C<\t> for a tab, C<\n> for a newline, C<\r> for a carriage return and C<\a> for a -bell. If your string is better thought of as a sequence of arbitrary +bell (or alert). If your string is better thought of as a sequence of arbitrary bytes, the octal escape sequence, e.g., C<\033>, or hexadecimal escape sequence, e.g., C<\x1B> may be a more natural representation for your bytes. Here are some examples of escapes: @@ -184,7 +184,8 @@ bytes. Here are some examples of escapes: "1000\t2000" =~ m(0\t2) # matches "1000\n2000" =~ /0\n20/ # matches "1000\t2000" =~ /\000\t2/ # doesn't match, "0" ne "\000" - "cat" =~ /\143\x61\x74/ # matches in ASCII, but a weird way to spell cat + "cat" =~ /\o{143}\x61\x74/ # matches in ASCII, but a weird way + # to spell cat If you've been around Perl a while, all this talk of escape sequences may seem familiar. Similar escape sequences are used in double-quoted @@ -286,7 +287,7 @@ Although one can already do quite a lot with the literal string regexps above, we've only scratched the surface of regular expression technology. In this and subsequent sections we will introduce regexp concepts (and associated metacharacter notations) that will allow a -regexp to not just represent a single character sequence, but a I<whole +regexp to represent not just a single character sequence, but a I<whole class> of them. One such concept is that of a I<character class>. A character class @@ -366,8 +367,9 @@ character, or the match fails. Then Now, even C<[0-9]> can be a bother to write multiple times, so in the interest of saving keystrokes and making regexps more readable, Perl has several abbreviations for common character classes, as shown below. -Since the introduction of Unicode, these character classes match more -than just a few characters in the ISO 8859-1 range. +Since the introduction of Unicode, unless the C<//a> modifier is in +effect, these character classes match more than just a few characters in +the ASCII range. =over 4 @@ -401,8 +403,22 @@ but also digits and characters from non-roman scripts The period '.' matches any character but "\n" (unless the modifier C<//s> is in effect, as explained below). +=item * + +\N, like the period, matches any character but "\n", but it does so +regardless of whether the modifier C<//s> is in effect. + =back +The C<//a> modifier, available starting in Perl 5.14, is used to +restrict the matches of \d, \s, and \w to just those in the ASCII range. +It is useful to keep your program from being needlessly exposed to full +Unicode (and its accompanying security considerations) when all you want +is to process English-like text. (The "a" may be doubled, C<//aa>, to +provide even more restrictions, preventing case-insensitive matching of +ASCII with non-ASCII characters; otherwise a Unicode "Kelvin Sign" +would caselessly match a "k" or "K".) + The C<\d\s\w\D\S\W> abbreviations can be used both inside and outside of character classes. Here are some in use: @@ -732,21 +748,21 @@ match). =head2 Backreferences Closely associated with the matching variables C<$1>, C<$2>, ... are -the I<backreferences> C<\1>, C<\2>,... Backreferences are simply +the I<backreferences> C<\g1>, C<\g2>,... Backreferences are simply matching variables that can be used I<inside> a regexp. This is a really nice feature; what matches later in a regexp is made to depend on what matched earlier in the regexp. Suppose we wanted to look for doubled words in a text, like 'the the'. The following regexp finds all 3-letter doubles with a space in between: - /\b(\w\w\w)\s\1\b/; + /\b(\w\w\w)\s\g1\b/; -The grouping assigns a value to \1, so that the same 3 letter sequence +The grouping assigns a value to \g1, so that the same 3-letter sequence is used for both parts. A similar task is to find words consisting of two identical parts: - % simple_grep '^(\w\w\w\w|\w\w\w|\w\w|\w)\1$' /usr/dict/words + % simple_grep '^(\w\w\w\w|\w\w\w|\w\w|\w)\g1$' /usr/dict/words beriberi booboo coco @@ -755,10 +771,10 @@ A similar task is to find words consisting of two identical parts: papa The regexp has a single grouping which considers 4-letter -combinations, then 3-letter combinations, etc., and uses C<\1> to look for -a repeat. Although C<$1> and C<\1> represent the same thing, care should be +combinations, then 3-letter combinations, etc., and uses C<\g1> to look for +a repeat. Although C<$1> and C<\g1> represent the same thing, care should be taken to use matched variables C<$1>, C<$2>,... only I<outside> a regexp -and backreferences C<\1>, C<\2>,... only I<inside> a regexp; not doing +and backreferences C<\g1>, C<\g2>,... only I<inside> a regexp; not doing so may lead to surprising and unsatisfactory results. @@ -772,10 +788,10 @@ preceding capture group one now may write C<\g{-1}>, the next but last is available via C<\g{-2}>, and so on. Another good reason in addition to readability and maintainability -for using relative backreferences is illustrated by the following example, +for using relative backreferences is illustrated by the following example, where a simple pattern for matching peculiar strings is used: - $a99a = '([a-z])(\d)\2\1'; # matches a11a, g22g, x33x, etc. + $a99a = '([a-z])(\d)\g2\g1'; # matches a11a, g22g, x33x, etc. Now that we have this pattern stored as a handy string, we might feel tempted to use it as a part of some other pattern: @@ -799,18 +815,18 @@ using relative backreferences: =head2 Named backreferences -Perl 5.10 also introduced named capture buffers and named backreferences. +Perl 5.10 also introduced named capture groups and named backreferences. To attach a name to a capturing group, you write either C<< (?<name>...) >> or C<< (?'name'...) >>. The backreference may then be written as C<\g{name}>. It is permissible to attach the same name to more than one group, but then only the leftmost one of the eponymous set can be referenced. Outside of the pattern a named -capture buffer is accessible through the C<%+> hash. +capture group is accessible through the C<%+> hash. Assuming that we have to match calendar dates which may be given in one of the three formats yyyy-mm-dd, mm/dd/yyyy or dd.mm.yyyy, we can write three suitable patterns where we use 'd', 'm' and 'y' respectively as the -names of the buffers capturing the pertaining components of a date. The +names of the groups capturing the pertaining components of a date. The matching operation combines the three patterns as alternatives: $fmt1 = '(?<y>\d\d\d\d)-(?<m>\d\d)-(?<d>\d\d)'; @@ -838,7 +854,7 @@ Consider a pattern for matching a time of the day, civil or military style: Processing the results requires an additional if statement to determine whether C<$1> and C<$2> or C<$3> and C<$4> contain the goodies. It would -be easier if we could use buffer numbers 1 and 2 in second alternative as +be easier if we could use group numbers 1 and 2 in second alternative as well, and this is exactly what the parenthesized construct C<(?|...)>, set around an alternative achieves. Here is an extended version of the previous pattern: @@ -847,7 +863,7 @@ previous pattern: print "hour=$1 minute=$2 zone=$3\n"; } -Within the alternative numbering group, buffer numbers start at the same +Within the alternative numbering group, group numbers start at the same position for each alternative. After the group, numbering continues with one higher than the maximum reached across all the alternatives. @@ -896,15 +912,18 @@ C<@+> instead: $& is the same as substr( $x, $-[0], $+[0]-$-[0] ) $' is the same as substr( $x, $+[0] ) +As of Perl 5.10, the C<${^PREMATCH}>, C<${^MATCH}> and C<${^POSTMATCH}> +variables may be used. These are only set if the C</p> modifier is present. +Consequently they do not penalize the rest of the program. =head2 Non-capturing groupings A group that is required to bundle a set of alternatives may or may not be useful as a capturing group. If it isn't, it just creates a superfluous -addition to the set of available capture buffer values, inside as well as +addition to the set of available capture group values, inside as well as outside the regexp. Non-capturing groupings, denoted by C<(?:regexp)>, still allow the regexp to be treated as a single unit, but don't establish -a capturing buffer at the same time. Both capturing and non-capturing +a capturing group at the same time. Both capturing and non-capturing groupings are allowed to co-exist in the same regexp. Because there is no extraction, non-capturing groupings are faster than capturing groupings. Non-capturing groupings are also handy for choosing exactly @@ -924,7 +943,7 @@ elements gathered from a split operation where parentheses are required for some reason: $x = '12aba34ba5'; - @num = split /(a|b)+/, $x; # @num = ('12','a','34','b','5') + @num = split /(a|b)+/, $x; # @num = ('12','a','34','a','5') @num = split /(?:a|b)+/, $x; # @num = ('12','34','5') @@ -976,15 +995,16 @@ Here are some examples: /[a-z]+\s+\d*/; # match a lowercase word, at least one space, and # any number of digits - /(\w+)\s+\1/; # match doubled words of arbitrary length + /(\w+)\s+\g1/; # match doubled words of arbitrary length /y(es)?/i; # matches 'y', 'Y', or a case-insensitive 'yes' - $year =~ /\d{2,4}/; # make sure year is at least 2 but not more - # than 4 digits - $year =~ /\d{4}|\d{2}/; # better match; throw out 3 digit dates - $year =~ /\d{2}(\d{2})?/; # same thing written differently. However, - # this produces $1 and the other does not. - - % simple_grep '^(\w+)\1$' /usr/dict/words # isn't this easier? + $year =~ /^\d{2,4}$/; # make sure year is at least 2 but not more + # than 4 digits + $year =~ /^\d{4}$|^\d{2}$/; # better match; throw out 3-digit dates + $year =~ /^\d{2}(\d{2})?$/; # same thing written differently. However, + # this captures the last two digits in $1 + # and the other does not. + + % simple_grep '^(\w+)\g1$' /usr/dict/words # isn't this easier? beriberi booboo coco @@ -1017,9 +1037,9 @@ stop there, but that wouldn't give the longest possible string to the first quantifier C<.*>. Instead, the first quantifier C<.*> grabs as much of the string as possible while still having the regexp match. In this example, that means having the C<at> sequence with the final C<at> -in the string. The other important principle illustrated here is that +in the string. The other important principle illustrated here is that, when there are two or more elements in a regexp, the I<leftmost> -quantifier, if there is one, gets to grab as much the string as +quantifier, if there is one, gets to grab as much of the string as possible, leaving the rest of the regexp to fight over scraps. Thus in our example, the first quantifier C<.*> grabs most of the string, while the second quantifier C<.*> gets the empty string. Quantifiers that @@ -1417,7 +1437,7 @@ we can rewrite our 'extended' regexp in the more pleasing form If whitespace is mostly irrelevant, how does one include space characters in an extended regexp? The answer is to backslash it S<C<'\ '>> or put it in a character class S<C<[ ]>>. The same thing -goes for pound signs, use C<\#> or C<[#]>. For instance, Perl allows +goes for pound signs: use C<\#> or C<[#]>. For instance, Perl allows a space between the sign and the mantissa or integer, and we could add this to our regexp as follows: @@ -1496,31 +1516,6 @@ single line C<//s>, multi-line C<//m>, case-insensitive C<//i> and extended C<//x> modifiers. There are a few more things you might want to know about matching operators. -=head3 Optimizing pattern evaluation - -We pointed out earlier that variables in regexps are substituted -before the regexp is evaluated: - - $pattern = 'Seuss'; - while (<>) { - print if /$pattern/; - } - -This will print any lines containing the word C<Seuss>. It is not as -efficient as it could be, however, because Perl has to re-evaluate -(or compile) C<$pattern> each time through the loop. If C<$pattern> won't be -changing over the lifetime of the script, we can add the C<//o> -modifier, which directs Perl to only perform variable substitutions -once: - - #!/usr/bin/perl - # Improved simple_grep - $regexp = shift; - while (<>) { - print if /$regexp/o; # a good deal faster - } - - =head3 Prohibiting substitution If you change C<$pattern> after the first substitution happens, Perl @@ -1542,11 +1537,12 @@ the regexp in the I<last successful match> is used instead. So we have =head3 Global matching -The final two modifiers C<//g> and C<//c> concern multiple matches. +The final two modifiers we will disccuss here, +C<//g> and C<//c>, concern multiple matches. The modifier C<//g> stands for global matching and allows the matching operator to match within a string as many times as possible. In scalar context, successive invocations against a string will have -`C<//g> jump from match to match, keeping track of position in the +C<//g> jump from match to match, keeping track of position in the string as it goes along. You can get or set the position with the C<pos()> function. @@ -1613,7 +1609,7 @@ bit at a time and use arbitrary Perl logic to decide what to do next. Currently, the C<\G> anchor is only fully supported when used to anchor to the start of the pattern. -C<\G> is also invaluable in processing fixed length records with +C<\G> is also invaluable in processing fixed-length records with regexps. Suppose we have a snippet of coding region DNA, encoded as base pair letters C<ATCGTTGAAT...> and we want to find all the stop codons C<TGA>. In a coding region, codons are 3-letter sequences, so @@ -1657,6 +1653,10 @@ which is the correct answer. This example illustrates that it is important not only to match what is desired, but to reject what is not desired. +(There are other regexp modifiers that are available, such as +C<//o>, C<//d>, and C<//l>, but their specialized uses are beyond the +scope of this introduction. ) + =head3 Search and replace Regular expressions also play a big role in I<search and replace> @@ -1664,11 +1664,11 @@ operations in Perl. Search and replace is accomplished with the C<s///> operator. The general form is C<s/regexp/replacement/modifiers>, with everything we know about regexps and modifiers applying in this case as well. The -C<replacement> is a Perl double quoted string that replaces in the +C<replacement> is a Perl double-quoted string that replaces in the string whatever is matched with the C<regexp>. The operator C<=~> is also used here to associate a string with C<s///>. If matching against C<$_>, the S<C<$_ =~>> can be dropped. If there is a match, -C<s///> returns the number of substitutions made, otherwise it returns +C<s///> returns the number of substitutions made; otherwise it returns false. Here are a few examples: $x = "Time to feed the cat!"; @@ -1682,7 +1682,7 @@ false. Here are a few examples: In the last example, the whole string was matched, but only the part inside the single quotes was grouped. With the C<s///> operator, the -matched variables C<$1>, C<$2>, etc. are immediately available for use +matched variables C<$1>, C<$2>, etc. are immediately available for use in the replacement expression, so we use C<$1> to replace the quoted string with just what was quoted. With the global modifier, C<s///g> will search and replace all occurrences of the regexp in the string: @@ -1702,7 +1702,7 @@ the following program to replace it: $regexp = shift; $replacement = shift; while (<>) { - s/$regexp/$replacement/go; + s/$regexp/$replacement/g; print; } ^D @@ -1710,13 +1710,41 @@ the following program to replace it: % simple_replace regexp regex perlretut.pod In C<simple_replace> we used the C<s///g> modifier to replace all -occurrences of the regexp on each line and the C<s///o> modifier to -compile the regexp only once. As with C<simple_grep>, both the -C<print> and the C<s/$regexp/$replacement/go> use C<$_> implicitly. +occurrences of the regexp on each line. (Even though the regular +expression appears in a loop, Perl is smart enough to compile it +only once.) As with C<simple_grep>, both the +C<print> and the C<s/$regexp/$replacement/g> use C<$_> implicitly. + +If you don't want C<s///> to change your original variable you can use +the non-destructive substitute modifier, C<s///r>. This changes the +behavior so that C<s///r> returns the final substituted string +(instead of the number of substitutions): + + $x = "I like dogs."; + $y = $x =~ s/dogs/cats/r; + print "$x $y\n"; + +That example will print "I like dogs. I like cats". Notice the original +C<$x> variable has not been affected. The overall +result of the substitution is instead stored in C<$y>. If the +substitution doesn't affect anything then the original string is +returned: + + $x = "I like dogs."; + $y = $x =~ s/elephants/cougars/r; + print "$x $y\n"; # prints "I like dogs. I like dogs." + +One other interesting thing that the C<s///r> flag allows is chaining +substitutions: + + $x = "Cats are great."; + print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~ s/Frogs/Hedgehogs/r, "\n"; + # prints "Hedgehogs are great." A modifier available specifically to search and replace is the -C<s///e> evaluation modifier. C<s///e> wraps an C<eval{...}> around -the replacement string and the evaluated result is substituted for the +C<s///e> evaluation modifier. C<s///e> treats the +replacement text as Perl code, rather than a double-quoted +string. The value that the code returns is substituted for the matched substring. C<s///e> is useful if you need to do a bit of computation in the process of replacing text. This example counts character frequencies in a line: @@ -1740,8 +1768,9 @@ This prints As with the match C<m//> operator, C<s///> can use other delimiters, such as C<s!!!> and C<s{}{}>, and even C<s{}//>. If single quotes are -used C<s'''>, then the regexp and replacement are treated as single -quoted strings and there are no substitutions. C<s///> in list context +used C<s'''>, then the regexp and replacement are +treated as single-quoted strings and there are no +variable substitutions. C<s///> in list context returns the same thing as in scalar context, i.e., the number of matches. @@ -1783,7 +1812,7 @@ an empty initial element to the list. If you have read this far, congratulations! You now have all the basic tools needed to use regular expressions to solve a wide range of text processing problems. If this is your first time through the tutorial, -why not stop here and play around with regexps a while... S<Part 2> +why not stop here and play around with regexps a while.... S<Part 2> concerns the more esoteric aspects of regular expressions and those concepts certainly aren't needed right at the start. @@ -1798,7 +1827,7 @@ too often on a hike, but when we are stuck, they can be invaluable. What follows are the more advanced, less used, or sometimes esoteric capabilities of Perl regexps. In Part 2, we will assume you are -comfortable with the basics and concentrate on the new features. +comfortable with the basics and concentrate on the advanced features. =head2 More on characters, strings, and character classes @@ -1839,21 +1868,27 @@ instance, It does not protect C<$> or C<@>, so that variables can still be substituted. +C<\Q>, C<\L>, C<\l>, C<\U>, C<\u> and C<\E> are actually part of +double-quotish syntax, and not part of regexp syntax proper. They will +work if they appear in a regular expression embeddded directly in a +program, but not when contained in a string that is interpolated in a +pattern. + With the advent of 5.6.0, Perl regexps can handle more than just the standard ASCII character set. Perl now supports I<Unicode>, a standard for representing the alphabets from virtually all of the world's written languages, and a host of symbols. Perl's text strings are Unicode strings, so they can contain characters with a value (codepoint or character number) higher -than 255 +than 255. What does this mean for regexps? Well, regexp users don't need to know much about Perl's internal representation of strings. But they do need to know 1) how to represent Unicode characters in a regexp and 2) that a matching operation will treat the string to be searched as a sequence of characters, not bytes. The answer to 1) is that Unicode characters -greater than C<chr(255)> are represented using the C<\x{hex}> notation, -because the \0 octal and \x hex (without curly braces) don't go further -than 255. +greater than C<chr(255)> are represented using the C<\x{hex}> notation, because +\x hex (without curly braces) doesn't go further than 255. (Starting in Perl +5.14, if you're an octal fan, you can also use C<\o{oct}>.) /\x{263a}/; # match a Unicode smiley face :) @@ -1887,15 +1922,21 @@ One can also use short names or restrict names to a certain alphabet: use charnames qw(greek); print "\N{sigma} is Greek sigma\n"; -A list of full names is found in the file NamesList.txt in the -lib/perl5/X.X.X/unicore directory (where X.X.X is the perl -version number as it is installed on your system). - -The answer to requirement 2), as of 5.6.0, is that a regexp uses Unicode -characters. Internally, this is encoded to bytes using either UTF-8 or a -native 8 bit encoding, depending on the history of the string, but -conceptually it is a sequence of characters, not bytes. See -L<perlunitut> for a tutorial about that. +A list of full names can be found in F<NamesList.txt> in the Unicode standard +(available at L<http://www.unicode.org/Public/UNIDATA/>). + +The answer to requirement 2), as of 5.6.0, is that a regexp (mostly) +uses Unicode characters. (For messy backward compatibility reasons, +most but not all semantics of a match will assume Unicode, unless, +starting in Perl 5.14, you tell it to use full Unicode. You can do this +explicitly by using the C<//u> modifier, or you can ask Perl to use the +modifier implicitly for all regexes in a scope by using C<use 5.012> (or +higher) or C<use feature 'unicode_strings'>.) If you want to handle +Unicode properly, you should ensure that one of these is the case.) +Internally, this is encoded to bytes using either UTF-8 or a native 8 +bit encoding, depending on the history of the string, but conceptually +it is a sequence of characters, not bytes. See L<perlunitut> for a +tutorial about that. Let us now discuss Unicode character classes. Just as with Unicode characters, there are named Unicode character classes represented by the @@ -1910,6 +1951,8 @@ example, to match lower and uppercase characters, $x =~ /^\p{IsLower}/; # doesn't match, lowercase char class $x =~ /^\P{IsLower}/; # matches, char class sans lowercase +(The "Is" is optional.) + Here is the association between some Perl named classes and the traditional Unicode classes: @@ -1931,21 +1974,18 @@ traditional Unicode classes: IsWord /^[LMN]/ || $code eq "005F" IsXDigit $code =~ /^00(3[0-9]|[46][1-6])$/ -You can also use the official Unicode class names with the C<\p> and -C<\P>, like C<\p{L}> for Unicode 'letters', or C<\p{Lu}> for uppercase +You can also use the official Unicode class names with C<\p> and +C<\P>, like C<\p{L}> for Unicode 'letters', C<\p{Lu}> for uppercase letters, or C<\P{Nd}> for non-digits. If a C<name> is just one letter, the braces can be dropped. For instance, C<\pM> is the character class of Unicode 'marks', for example accent marks. For the full list see L<perlunicode>. -The Unicode has also been separated into various sets of characters +Unicode has also been separated into various sets of characters which you can test with C<\p{...}> (in) and C<\P{...}> (not in). To test whether a character is (or is not) an element of a script you would use the script name, for example C<\p{Latin}>, C<\p{Greek}>, -or C<\P{Katakana}>. Other sets are the Unicode blocks, the names -of which begin with "In". One such block is dedicated to mathematical -operators, and its pattern formula is <C\p{InMathematicalOperators>}>. -For the full list see L<perluniprops>. +or C<\P{Katakana}>. What we have described so far is the single form of the C<\p{...}> character classes. There is also a compound form which you may run into. These @@ -1959,7 +1999,7 @@ never have to use the compound forms, but sometimes it is necessary, and their use can make your code easier to understand. C<\X> is an abbreviation for a character class that comprises -a Unicode I<extended grapheme cluster>. This represents a "logical character", +a Unicode I<extended grapheme cluster>. This represents a "logical character": what appears to be a single character, but may be represented internally by more than one. As an example, using the Unicode full names, e.g., S<C<A + COMBINING RING>> is a grapheme cluster with base character C<A> and combining character @@ -1969,27 +2009,27 @@ as in the word Angstrom. For the full and latest information about Unicode see the latest Unicode standard, or the Unicode Consortium's website L<http://www.unicode.org> -As if all those classes weren't enough, Perl also defines POSIX style +As if all those classes weren't enough, Perl also defines POSIX-style character classes. These have the form C<[:name:]>, with C<name> the name of the POSIX class. The POSIX classes are C<alpha>, C<alnum>, C<ascii>, C<cntrl>, C<digit>, C<graph>, C<lower>, C<print>, C<punct>, C<space>, C<upper>, and C<xdigit>, and two extensions, C<word> (a Perl -extension to match C<\w>), and C<blank> (a GNU extension). If C<utf8> -is being used, then these classes are defined the same as their -corresponding Perl Unicode classes: C<[:upper:]> is the same as -C<\p{IsUpper}>, etc. The POSIX character classes, however, don't -require using C<utf8>. The C<[:digit:]>, C<[:word:]>, and +extension to match C<\w>), and C<blank> (a GNU extension). The C<//a> +modifier restricts these to matching just in the ASCII range; otherwise +they can match the same as their corresponding Perl Unicode classes: +C<[:upper:]> is the same as C<\p{IsUpper}>, etc. (There are some +exceptions and gotchas with this; see L<perlrecharclass> for a full +discussion.) The C<[:digit:]>, C<[:word:]>, and C<[:space:]> correspond to the familiar C<\d>, C<\w>, and C<\s> character classes. To negate a POSIX class, put a C<^> in front of -the name, so that, e.g., C<[:^digit:]> corresponds to C<\D> and under -C<utf8>, C<\P{IsDigit}>. The Unicode and POSIX character classes can +the name, so that, e.g., C<[:^digit:]> corresponds to C<\D> and, under +Unicode, C<\P{IsDigit}>. The Unicode and POSIX character classes can be used just like C<\d>, with the exception that POSIX character classes can only be used inside of a character class: /\s+[abc[:digit:]xyz]\s*/; # match a,b,c,x,y,z, or a digit /^=item\s[[:digit:]]/; # match '=item', # followed by a space and a digit - use charnames ":full"; /\s+[abc\p{IsDigit}xyz]\s+/; # match a,b,c,x,y,z, or a digit /^=item\s\p{IsDigit}/; # match '=item', # followed by a space and a digit @@ -1998,8 +2038,8 @@ Whew! That is all the rest of the characters and character classes. =head2 Compiling and saving regular expressions -In Part 1 we discussed the C<//o> modifier, which compiles a regexp -just once. This suggests that a compiled regexp is some data structure +In Part 1 we mentioned that Perl compiles a regexp into a compact +sequence of opcodes. Thus, a compiled regexp is a data structure that can be stored once and used again and again. The regexp quote C<qr//> does exactly that: C<qr/string/> compiles the C<string> as a regexp and transforms the result into a form that can be assigned to a @@ -2074,7 +2114,7 @@ multiple patterns: $pattern = join '|', @regexp; while ($line = <>) { - print $line if $line =~ /$pattern/o; + print $line if $line =~ /$pattern/; } ^D @@ -2128,8 +2168,8 @@ Starting with this section, we will be discussing Perl's set of I<extended patterns>. These are extensions to the traditional regular expression syntax that provide powerful new tools for pattern matching. We have already seen extensions in the form of the minimal -matching constructs C<??>, C<*?>, C<+?>, C<{n,m}?>, and C<{n,}?>. The -rest of the extensions below have the form C<(?char...)>, where the +matching constructs C<??>, C<*?>, C<+?>, C<{n,m}?>, and C<{n,}?>. Most +of the extensions below have the form C<(?char...)>, where the C<char> is a character that determines the type of extension. The first extension is an embedded comment C<(?#text)>. This embeds a @@ -2142,7 +2182,7 @@ example is This style of commenting has been largely superseded by the raw, freeform commenting that is allowed with the C<//x> modifier. -The modifiers C<//i>, C<//m>, C<//s> and C<//x> (or any +Most modifiers, such as C<//i>, C<//m>, C<//s> and C<//x> (or any combination thereof) can also be embedded in a regexp using C<(?i)>, C<(?m)>, C<(?s)>, and C<(?x)>. For instance, @@ -2200,8 +2240,8 @@ we have seen so far are the anchors. The anchor C<^> matches the beginning of the line, but doesn't eat any characters. Similarly, the word boundary anchor C<\b> matches wherever a character matching C<\w> is next to a character that doesn't, but it doesn't eat up any -characters itself. Anchors are examples of I<zero-width assertions>. -Zero-width, because they consume +characters itself. Anchors are examples of I<zero-width assertions>: +zero-width, because they consume no characters, and assertions, because they test some property of the string. In the context of our walk in the woods analogy to regexp matching, most regexp elements move us along a trail, but anchors have @@ -2347,9 +2387,9 @@ matched, otherwise the C<no-regexp> will be matched. The C<condition> can have several forms. The first form is simply an integer in parentheses C<(integer)>. It is true if the corresponding backreference C<\integer> matched earlier in the regexp. The same -thing can be done with a name associated with a capture buffer, written +thing can be done with a name associated with a capture group, written as C<< (<name>) >> or C<< ('name') >>. The second form is a bare -zero width assertion C<(?...)>, either a lookahead, a lookbehind, or a +zero-width assertion C<(?...)>, either a lookahead, a lookbehind, or a code assertion (discussed in the next section). The third set of forms provides tests that return true if the expression is executed within a recursion (C<(R)>) or is being called from some capturing group, @@ -2360,7 +2400,7 @@ The integer or name form of the C<condition> allows us to choose, with more flexibility, what to match based on what matched earlier in the regexp. This searches for words of the form C<"$x$x"> or C<"$x$y$y$x">: - % simple_grep '^(\w+)(\w+)?(?(2)\2\1|\1)$' /usr/dict/words + % simple_grep '^(\w+)(\w+)?(?(2)\g2\g1|\g1)$' /usr/dict/words beriberi coco couscous @@ -2441,8 +2481,8 @@ have the full pattern: In C<(?...)> both absolute and relative backreferences may be used. The entire pattern can be reinserted with C<(?R)> or C<(?0)>. -If you prefer to name your buffers, you can use C<(?&name)> to -recurse into that buffer. +If you prefer to name your groups, you can use C<(?&name)> to +recurse into that group. =head2 A bit of magic: executing Perl code in a regular expression @@ -2683,23 +2723,24 @@ detailed description. Below is just one example, illustrating the control verb C<(*FAIL)>, which may be abbreviated as C<(*F)>. If this is inserted in a regexp -it will cause to fail, just like at some mismatch between the pattern -and the string. Processing of the regexp continues like after any "normal" +it will cause it to fail, just as it would at some +mismatch between the pattern and the string. Processing +of the regexp continues as it would after any "normal" failure, so that, for instance, the next position in the string or another alternative will be tried. As failing to match doesn't preserve capture -buffers or produce results, it may be necessary to use this in +groups or produce results, it may be necessary to use this in combination with embedded code. %count = (); "supercalifragilisticexpialidoceous" =~ - /([aeiou])(?{ $count{$1}++; })(*FAIL)/oi; + /([aeiou])(?{ $count{$1}++; })(*FAIL)/i; printf "%3d '%s'\n", $count{$_}, $_ for (sort keys %count); The pattern begins with a class matching a subset of letters. Whenever this matches, a statement like C<$count{'a'}++;> is executed, incrementing the letter's counter. Then C<(*FAIL)> does what it says, and -the regexp engine proceeds according to the book: as long as the end of -the string hasn't been reached, the position is advanced before looking +the regexp engine proceeds according to the book: as long as the end of +the string hasn't been reached, the position is advanced before looking for another vowel. Thus, match or no match makes no difference, and the regexp engine proceeds until the entire string has been inspected. (It's remarkable that an alternative solution using something like @@ -2730,6 +2771,14 @@ performing some other processing. Both C<taint> and C<eval> pragmas are lexically scoped, which means they are in effect only until the end of the block enclosing the pragmas. + use re '/m'; # or any other flags + $multiline_string =~ /^foo/; # /m is implied + +The C<re '/flags'> pragma (introduced in Perl +5.14) turns on the given regular expression flags +until the end of the lexical scope. See C<re/"'/flags' mode"> for more +detail. + use re 'debug'; /^(.*)$/s; # output debugging info @@ -2810,8 +2859,8 @@ process: Each step is of the form S<C<< n <x> <y> >>>, with C<< <x> >> the part of the string matched and C<< <y> >> the part not yet matched. The S<C<< | 1: STAR >>> says that Perl is at line number 1 -n the compilation list above. See -L<perldebguts/"Debugging regular expressions"> for much more detail. +in the compilation list above. See +L<perldebguts/"Debugging Regular Expressions"> for much more detail. An alternative method of debugging regexps is to embed C<print> statements within the regexp. This provides a blow-by-blow account of diff --git a/Master/tlpkg/tlperl/lib/pods/perlriscos.pod b/Master/tlpkg/tlperl/lib/pods/perlriscos.pod index 93c365bf654..62a1a5647c7 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlriscos.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlriscos.pod @@ -25,11 +25,11 @@ Then, in the source to be cross compiled: =over 4 -=item +=item 1. $ ./Configure -=item +=item 2. Select the riscos hint file. The default answers for the rest of the questions are usually sufficient. @@ -39,24 +39,24 @@ document for details), to have it select the correct hint file, you'll need to provide the argument -Dhintfile=riscos on the Configure command-line. -=item +=item 3. $ make miniperl -=item +=item 4. This should build miniperl and then fail when it tries to run it. -=item +=item 5. Copy the miniperl executable from the native build done earlier to replace the cross compiled miniperl. -=item +=item 6. $ make -=item +=item 7. This will use miniperl to complete the rest of the build. diff --git a/Master/tlpkg/tlperl/lib/pods/perlrun.pod b/Master/tlpkg/tlperl/lib/pods/perlrun.pod index 75e7ce10097..d51342f8f80 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlrun.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlrun.pod @@ -33,7 +33,7 @@ Specified line by line via B<-e> or B<-E> switches on the command line. =item 2. Contained in the file specified by the first filename on the command line. -(Note that systems supporting the #! notation invoke interpreters this +(Note that systems supporting the C<#!> notation invoke interpreters this way. See L<Location of Perl>.) =item 3. @@ -46,19 +46,19 @@ must explicitly specify a "-" for the program name. With methods 2 and 3, Perl starts parsing the input file from the beginning, unless you've specified a B<-x> switch, in which case it -scans for the first line starting with #! and containing the word +scans for the first line starting with C<#!> and containing the word "perl", and starts there instead. This is useful for running a program embedded in a larger message. (In this case you would indicate the end of the program using the C<__END__> token.) -The #! line is always examined for switches as the line is being +The C<#!> line is always examined for switches as the line is being parsed. Thus, if you're on a machine that allows only one argument -with the #! line, or worse, doesn't even recognize the #! line, you -still can get consistent switch behavior regardless of how Perl was +with the C<#!> line, or worse, doesn't even recognize the C<#!> line, you +still can get consistent switch behaviour regardless of how Perl was invoked, even if B<-x> was used to find the beginning of the program. Because historically some operating systems silently chopped off -kernel interpretation of the #! line after 32 characters, some +kernel interpretation of the C<#!> line after 32 characters, some switches may be passed in on the command line, and some may not; you could even get a "-" without its letter, if you're not careful. You probably want to make sure that all your switches fall either @@ -73,7 +73,7 @@ combinations of B<-l> and B<-0>. Either put all the switches after the 32-character boundary (if applicable), or replace the use of B<-0>I<digits> by C<BEGIN{ $/ = "\0digits"; }>. -Parsing of the #! switches starts wherever "perl" is mentioned in the line. +Parsing of the C<#!> 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 @@ -84,18 +84,18 @@ if you were so inclined, say to let Perl see the B<-p> switch. -A similar trick involves the B<env> program, if you have it. +A similar trick involves the I<env> program, if you have it. #!/usr/bin/env perl The examples above use a relative path to the perl interpreter, getting whatever version is first in the user's path. If you want a specific version of Perl, say, perl5.005_57, you should place -that directly in the #! line's path. +that directly in the C<#!> line's path. -If the #! line does not contain the word "perl", the program named after -the #! is executed instead of the Perl interpreter. This is slightly -bizarre, but it helps people on machines that don't do #!, because they +If the C<#!> line does not contain the word "perl", the program named after +the C<#!> is executed instead of the Perl interpreter. This is slightly +bizarre, but it helps people on machines that don't do C<#!>, because they can tell a program that their SHELL is F</usr/bin/perl>, and Perl will then dispatch the program to the correct interpreter for them. @@ -111,7 +111,7 @@ C<exit(0)> is provided to indicate successful completion. =head2 #! and quoting on non-Unix systems X<hashbang> X<#!> -Unix's #! technique can be simulated on other systems: +Unix's C<#!> technique can be simulated on other systems: =over 4 @@ -178,7 +178,7 @@ For example: perl -e "print ""Hello world\n""" The problem is that none of this is reliable: it depends on the -command and it is entirely possible neither works. If B<4DOS> were +command and it is entirely possible neither works. If I<4DOS> were the command shell, this would probably work better: perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" @@ -229,7 +229,7 @@ X<-0> X<$/> specifies the input record separator (C<$/>) as an octal or hexadecimal number. If there are no digits, the null character is the separator. Other switches may precede or follow the digits. For -example, if you have a version of B<find> which can print filenames +example, if you have a version of I<find> which can print filenames terminated by the null character, you can say this: find . -name '*.orig' -print0 | perl -n0e unlink @@ -239,11 +239,12 @@ Any value 0400 or above will cause Perl to slurp files whole, but by convention the value 0777 is the one normally used for this purpose. You can also specify the separator character using hexadecimal notation: -C<-0xHHH...>, where the C<H> are valid hexadecimal digits. Unlike the octal -form, this one may be used to specify any Unicode character, even those beyond -0xFF. -(This means that you cannot use the C<-x> with a directory name that -consists of hexadecimal digits.) +B<-0xI<HHH...>>, where the C<I<H>> are valid hexadecimal digits. Unlike +the octal form, this one may be used to specify any Unicode character, even +those beyond 0xFF. So if you I<really> want a record separator of 0777, +specify it as B<-0x1FF>. (This means that you cannot use the B<-x> option +with a directory name that consists of hexadecimal digits, or else Perl +will think you have specified a hex number to B<-0>.) =item B<-a> X<-a> X<autosplit> @@ -266,9 +267,9 @@ An alternate delimiter may be specified using B<-F>. =item B<-C [I<number/list>]> X<-C> -The C<-C> flag controls some of the Perl Unicode features. +The B<-C> flag controls some of the Perl Unicode features. -As of 5.8.1, the C<-C> can be followed either by a number or a list +As of 5.8.1, the B<-C> can be followed either by a number or a list of option letters. The letters, their numeric values, and effects are as follows; listing the letters is equal to summing the numbers. @@ -296,25 +297,25 @@ perl.h gives W/128 as PERL_UNICODE_WIDESYSCALLS "/* for Sarathy */" perltodo mentions Unicode in %ENV and filenames. I guess that these will be options e and f (or F). -For example, C<-COE> and C<-C6> will both turn on UTF-8-ness on both +For example, B<-COE> and B<-C6> will both turn on UTF-8-ness on both STDOUT and STDERR. Repeating letters is just redundant, not cumulative nor toggling. The C<io> options mean that any subsequent open() (or similar I/O -operations) will have the C<:utf8> PerlIO layer implicitly applied -to them, in other words, UTF-8 is expected from any input stream, -and UTF-8 is produced to any output stream. This is just the default, -with explicit layers in open() and with binmode() one can manipulate -streams as usual. +operations) in the current file scope will have the C<:utf8> PerlIO layer +implicitly applied to them, in other words, UTF-8 is expected from any +input stream, and UTF-8 is produced to any output stream. This is just +the default, with explicit layers in open() and with binmode() one can +manipulate streams as usual. -C<-C> on its own (not followed by any number or option list), or the +B<-C> on its own (not followed by any number or option list), or the empty string C<""> for the C<PERL_UNICODE> environment variable, has the -same effect as C<-CSDL>. In other words, the standard I/O handles and -the default C<open()> layer are UTF-8-fied B<but> only if the locale +same effect as B<-CSDL>. In other words, the standard I/O handles and +the default C<open()> layer are UTF-8-fied I<but> only if the locale environment variables indicate a UTF-8 locale. This behaviour follows the I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0. -You can use C<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly +You can use B<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly disable all the above Unicode features. The read-only magic variable C<${^UNICODE}> reflects the numeric value @@ -323,13 +324,13 @@ thereafter read-only. If you want runtime effects, use the three-arg open() (see L<perlfunc/open>), the two-arg binmode() (see L<perlfunc/binmode>), and the C<open> pragma (see L<open>). -(In Perls earlier than 5.8.1 the C<-C> switch was a Win32-only switch +(In Perls earlier than 5.8.1 the B<-C> switch was a Win32-only switch 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.1, if the -C option is used on the #! line, it -must be specified on the command line as well, since the standard streams +B<Note:> Since perl 5.10.1, if the B<-C> option is used on the C<#!> line, +it must be specified on the command line as well, since the standard streams are already set up at this point in the execution of the perl interpreter. You can also use binmode() to set the encoding of an I/O stream. @@ -337,10 +338,10 @@ You can also use binmode() to set the encoding of an I/O stream. X<-c> causes Perl to check the syntax of the program and then exit without -executing it. Actually, it I<will> execute C<BEGIN>, C<UNITCHECK>, -C<CHECK>, and C<use> blocks, because these are considered as occurring -outside the execution of your program. C<INIT> and C<END> blocks, -however, will be skipped. +executing it. Actually, it I<will> execute and C<BEGIN>, C<UNITCHECK>, +or C<CHECK> blocks and any C<use> statements: these are considered as +occurring outside the execution of your program. C<INIT> and C<END> +blocks, however, will be skipped. =item B<-d> X<-d> X<-dt> @@ -351,20 +352,20 @@ runs the program under the Perl debugger. See L<perldebug>. If B<t> is specified, it indicates to the debugger that threads will be used in the code being debugged. -=item B<-d:>I<foo[=bar,baz]> +=item B<-d:>I<MOD[=bar,baz]> X<-d> X<-dt> -=item B<-dt:>I<foo[=bar,baz]> +=item B<-dt:>I<MOD[=bar,baz]> -runs the program under the control of a debugging, profiling, or -tracing module installed as Devel::foo. E.g., B<-d:DProf> executes -the program using the Devel::DProf profiler. As with the B<-M> -flag, options may be passed to the Devel::foo package where they -will be received and interpreted by the Devel::foo::import routine. -The comma-separated list of options must follow a C<=> character. -If B<t> is specified, it indicates to the debugger that threads -will be used in the code being debugged. -See L<perldebug>. +runs the program under the control of a debugging, profiling, or tracing +module installed as C<Devel::I<MOD>>. E.g., B<-d:DProf> executes the +program using the C<Devel::DProf> profiler. As with the B<-M> flag, options +may be passed to the C<Devel::I<MOD>> package where they will be received +and interpreted by the C<Devel::I<MOD>::import> routine. Again, like B<-M>, +use -B<-d:-I<MOD>> to call C<Devel::I<MOD>::unimport> instead of import. The +comma-separated list of options must follow a C<=> character. If B<t> is +specified, it indicates to the debugger that threads will be used in the +code being debugged. See L<perldebug>. =item B<-D>I<letters> X<-D> X<DEBUGGING> X<-DDEBUGGING> @@ -396,9 +397,9 @@ B<-D14> is equivalent to B<-Dtls>): 8192 H Hash dump -- usurps values() 16384 X Scratchpad allocation 32768 D Cleaning up - 131072 T Tokenising + 131072 T Tokenizing 262144 R Include reference counts of dumped variables (eg when using -Ds) - 524288 J Do not s,t,P-debug (Jump over) opcodes within package DB + 524288 J show s,t,P-debug (don't Jump over) on opcodes within package DB 1048576 v Verbose: use in conjunction with other flags 2097152 C Copy On Write 4194304 A Consistency checks on internal structures @@ -407,7 +408,8 @@ B<-D14> is equivalent to B<-Dtls>): 33554432 B dump suBroutine definitions, including special Blocks like BEGIN All these flags require B<-DDEBUGGING> when you compile the Perl -executable (but see L<Devel::Peek>, L<re> which may change this). +executable (but see C<:opd> in L<Devel::Peek> or L<re/'debug' mode> +which may change this). See the F<INSTALL> file in the Perl source distribution for how to do this. This flag is automatically set if you include B<-g> option when C<Configure> asks you about optimizer/debugger flags. @@ -448,8 +450,8 @@ Disable executing F<$Config{sitelib}/sitecustomize.pl> at startup. Perl can be built so that it by default will try to execute F<$Config{sitelib}/sitecustomize.pl> at startup (in a BEGIN block). -This is a hook that allows the sysadmin to customize how perl behaves. -It can for instance be used to add entries to the @INC array to make perl +This is a hook that allows the sysadmin to customize how Perl behaves. +It can for instance be used to add entries to the @INC array to make Perl find modules in non-standard locations. Perl actually inserts the following code: @@ -467,7 +469,7 @@ be set. The value of C<$Config{sitelib}> is also determined in C code and not read from C<Config.pm>, which is not loaded. -The code is executed B<very> early. For example, any changes made to +The code is executed I<very> early. For example, any changes made to C<@INC> will show up in the output of `perl -V`. Of course, C<END> blocks will be likewise executed very late. @@ -639,28 +641,28 @@ program. B<-M>I<module> executes C<use> I<module> C<;> before executing your program. You can use quotes to add extra code after the module name, -e.g., C<'-Mmodule qw(foo bar)'>. +e.g., C<'-MI<MODULE> qw(foo bar)'>. -If the first character after the B<-M> or B<-m> is a dash (C<->) +If the first character after the B<-M> or B<-m> is a dash (B<->) then the 'use' is replaced with 'no'. A little builtin syntactic sugar means you can also say -B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for -C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when -importing symbols. The actual code generated by B<-Mmodule=foo,bar> is +B<-mI<MODULE>=foo,bar> or B<-MI<MODULE>=foo,bar> as a shortcut for +B<'-MI<MODULE> qw(foo bar)'>. This avoids the need to use quotes when +importing symbols. The actual code generated by B<-MI<MODULE>=foo,bar> is C<use module split(/,/,q{foo,bar})>. Note that the C<=> form removes the distinction between B<-m> and B<-M>. -A consequence of this is that B<-MFoo=number> never does a version check -(unless C<Foo::import()> itself is set up to do a version check, which -could happen for example if Foo inherits from Exporter.) +A consequence of this is that B<-MI<MODULE>=number> never does a version check, +unless C<I<MODULE>::import()> itself is set up to do a version check, which +could happen for example if I<MODULE> inherits from L<Exporter>. =item B<-n> X<-n> causes Perl to assume the following loop around your program, which -makes it iterate over filename arguments somewhat like B<sed -n> or -B<awk>: +makes it iterate over filename arguments somewhat like I<sed -n> or +I<awk>: LINE: while (<>) { @@ -680,19 +682,19 @@ at least a week: find . -mtime +7 -print | perl -nle unlink -This is faster than using the B<-exec> switch of B<find> because you don't +This is faster than using the B<-exec> switch of I<find> because you don't have to start a process on every filename found. It does suffer from the bug of mishandling newlines in pathnames, which you can fix if you follow the example under B<-0>. C<BEGIN> and C<END> blocks may be used to capture control before or after -the implicit program loop, just as in B<awk>. +the implicit program loop, just as in I<awk>. =item B<-p> X<-p> causes Perl to assume the following loop around your program, which -makes it iterate over filename arguments somewhat like B<sed>: +makes it iterate over filename arguments somewhat like I<sed>: LINE: @@ -709,7 +711,7 @@ treated as fatal. To suppress printing use the B<-n> switch. A B<-p> overrides a B<-n> switch. C<BEGIN> and C<END> blocks may be used to capture control before or after -the implicit loop, just as in B<awk>. +the implicit loop, just as in I<awk>. =item B<-s> X<-s> @@ -724,25 +726,25 @@ if it is invoked with B<-xyz=abc>. #!/usr/bin/perl -s if ($xyz) { print "$xyz\n" } -Do note that a switch like B<--help> creates the variable ${-help}, which is not compliant -with C<strict refs>. Also, when using this option on a script with +Do note that a switch like B<--help> creates the variable C<${-help}>, which is not compliant +with C<use strict "refs">. Also, when using this option on a script with warnings enabled you may get a lot of spurious "used only once" warnings. =item B<-S> X<-S> makes Perl use the PATH environment variable to search for the -program (unless the name of the program contains directory separators). +program unless the name of the program contains path separators. On some platforms, this also makes Perl append suffixes to the filename while searching for it. For example, on Win32 platforms, the ".bat" and ".cmd" suffixes are appended if a lookup for the original name fails, and if the name does not already end in one -of those suffixes. If your Perl was compiled with DEBUGGING turned -on, using the -Dp switch to Perl shows how the search progresses. +of those suffixes. If your Perl was compiled with C<DEBUGGING> turned +on, using the B<-Dp> switch to Perl shows how the search progresses. -Typically this is used to emulate #! startup on platforms that don't -support #!. Its also convenient when debugging a script that uses #!, +Typically this is used to emulate C<#!> startup on platforms that don't +support C<#!>. It's also convenient when debugging a script that uses C<#!>, and is thus normally found by the shell's $PATH search mechanism. This example works on many platforms that have a shell compatible with @@ -761,17 +763,17 @@ program if necessary. After Perl locates the program, it parses the lines and ignores them because the variable $running_under_some_shell is never true. If the program will be interpreted by csh, you will need to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand -embedded spaces (and such) in the argument list. To start up sh rather -than csh, some systems may have to replace the #! line with a line +embedded spaces (and such) in the argument list. To start up I<sh> rather +than I<csh>, some systems may have to replace the C<#!> line with a line containing just a colon, which will be politely ignored by Perl. Other systems can't control that, and need a totally devious construct that -will work under any of B<csh>, B<sh>, or Perl, such as the following: +will work under any of I<csh>, I<sh>, or Perl, such as the following: eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}' & eval 'exec /usr/bin/perl -wS $0 $argv:q' if $running_under_some_shell; -If the filename supplied contains directory separators (i.e., is an +If the filename supplied contains directory separators (and so is an absolute or relative pathname), and if that file is not found, platforms that append file extensions will do so and try to look for the file with those extensions added, one by one. @@ -785,49 +787,48 @@ program will be searched for strictly on the PATH. X<-t> Like B<-T>, but taint checks will issue warnings rather than fatal -errors. These warnings can be controlled normally with C<no warnings +errors. These warnings can now be controlled normally with C<no warnings qw(taint)>. -B<NOTE: this is not a substitute for -T.> This is meant only to be -used as a temporary development aid while securing legacy code: -for real production code and for new secure code written from scratch +B<Note: This is not a substitute for C<-T>!> This is meant to be +used I<only> as a temporary development aid while securing legacy code: +for real production code and for new secure code written from scratch, always use the real B<-T>. =item B<-T> X<-T> -forces "taint" checks to be turned on so you can test them. Ordinarily +turns on "taint" so you can test them. Ordinarily these checks are done only when running setuid or setgid. It's a good idea to turn them on explicitly for programs that run on behalf of someone else whom you might not necessarily trust, such as CGI programs or any internet servers you might write in Perl. See L<perlsec> for details. For security reasons, this option must be seen by Perl quite early; usually this means it must appear early -on the command line or in the #! line for systems which support +on the command line or in the C<#!> line for systems which support that construct. =item B<-u> X<-u> -This obsolete switch causes Perl to dump core after compiling your +This switch causes Perl to dump core after compiling your program. You can then in theory take this core dump and turn it -into an executable file by using the B<undump> program (not supplied). +into an executable file by using the I<undump> program (not supplied). This speeds startup at the expense of some disk space (which you can minimize by stripping the executable). (Still, a "hello world" executable comes out to about 200K on my machine.) If you want to execute a portion of your program before dumping, use the dump() -operator instead. Note: availability of B<undump> is platform +operator instead. Note: availability of I<undump> is platform specific and may not be available for a specific port of Perl. =item B<-U> X<-U> allows Perl to do unsafe operations. Currently the only "unsafe" -operations are attempting to unlink directories while running as -superuser, and running setuid programs with fatal taint checks turned -into warnings. Note that the B<-w> switch (or the C<$^W> variable) -must be used along with this option to actually I<generate> the -taint-check warnings. +operations are attempting to unlink directories while running as superuser +and running setuid programs with fatal taint checks turned into warnings. +Note that warnings must be enabled along with this option to actually +I<generate> the taint-check warnings. =item B<-v> X<-v> @@ -843,7 +844,7 @@ values of @INC. =item B<-V:>I<configvar> Prints to STDOUT the value of the named configuration variable(s), -with multiples when your configvar argument looks like a regex (has +with multiples when your C<I<configvar>> argument looks like a regex (has non-letters). For example: $ perl -V:libc @@ -860,14 +861,14 @@ non-letters). For example: .... Additionally, extra colons can be used to control formatting. A -trailing colon suppresses the linefeed and terminator ';', allowing +trailing colon suppresses the linefeed and terminator ";", allowing you to embed queries into shell commands. (mnemonic: PATH separator -':'.) +":".) $ echo "compression-vars: " `perl -V:z.*: ` " are here !" compression-vars: zcat='' zip='zip' are here ! -A leading colon removes the 'name=' part of the response, this allows +A leading colon removes the "name=" part of the response, this allows you to map to the name you need. (mnemonic: empty label) $ echo "goodvfork="`./perl -Ilib -V::usevfork` @@ -875,7 +876,7 @@ you to map to the name you need. (mnemonic: empty label) Leading and trailing colons can be used together if you need positional parameter values without the names. Note that in the case -below, the PERL_API params are returned in alphabetical order. +below, the C<PERL_API> params are returned in alphabetical order. $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now building_on 'linux' '5' '1' '9' now @@ -884,17 +885,18 @@ below, the PERL_API params are returned in alphabetical order. X<-w> prints warnings about dubious constructs, such as variable names -that are mentioned only once and scalar variables that are used -before being set, redefined subroutines, references to undefined -filehandles or filehandles opened read-only that you are attempting -to write on, values used as a number that don't look like numbers, -using an array as though it were a scalar, if your subroutines -recurse more than 100 deep, and innumerable other things. - -This switch really just enables the internal C<$^W> variable. You +mentioned only once and scalar variables used +before being set; redefined subroutines; references to undefined +filehandles; filehandles opened read-only that you are attempting +to write on; values used as a number that don't I<look> like numbers; +using an array as though it were a scalar; if your subroutines +recurse more than 100 deep; and innumerable other things. + +This switch really just enables the global C<$^W> variable; normally, +the lexically scoped C<use warnings> pragma is preferred. You can disable or promote into fatal errors specific warnings using C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>. -See also L<perldiag> and L<perltrap>. A new, fine-grained warning +See also L<perldiag> and L<perltrap>. A fine-grained warning facility is also available if you want to manipulate entire classes of warnings; see L<warnings> or L<perllexwarn>. @@ -916,23 +918,23 @@ X<-x> =item B<-x>I<directory> tells Perl that the program is embedded in a larger chunk of unrelated -ASCII text, such as in a mail message. Leading garbage will be -discarded until the first line that starts with #! and contains the +text, such as in a mail message. Leading garbage will be +discarded until the first line that starts with C<#!> and contains the string "perl". Any meaningful switches on that line will be applied. All references to line numbers by the program (warnings, errors, ...) -will treat the #! line as the first line. -Thus a warning on the 2nd line of the program (which is on the 100th -line in the file) will be reported as line 2, and not as line 100. -This can be overridden by using the #line directive. -(See L<perlsyn/"Plain-Old-Comments-(Not!)">) +will treat the C<#!> line as the first line. +Thus a warning on the 2nd line of the program, which is on the 100th +line in the file will be reported as line 2, not as line 100. +This can be overridden by using the C<#line> directive. +(See L<perlsyn/"Plain Old Comments (Not!)">) If a directory name is specified, Perl will switch to that directory before running the program. The B<-x> switch controls only the disposal of leading garbage. The program must be terminated with -C<__END__> if there is trailing garbage to be ignored (the program -can process any or all of the trailing garbage via the DATA filehandle -if desired). +C<__END__> if there is trailing garbage to be ignored; the program +can process any or all of the trailing garbage via the C<DATA> filehandle +if desired. The directory, if specified, must appear immediately following the B<-x> with no intervening whitespace. @@ -947,12 +949,12 @@ X<perl, environment variables> =item HOME X<HOME> -Used if chdir has no argument. +Used if C<chdir> has no argument. =item LOGDIR X<LOGDIR> -Used if chdir has no argument and HOME is not set. +Used if C<chdir> has no argument and HOME is not set. =item PATH X<PATH> @@ -966,66 +968,68 @@ X<PERL5LIB> A list of directories in which to look for Perl library files before looking in the standard library and the current directory. Any architecture-specific directories under the specified -locations are automatically included if they exist (this lookup -being done at interpreter startup time.) +locations are automatically included if they exist, with this lookup +done at interpreter startup time. If PERL5LIB is not defined, PERLLIB is used. Directories are separated (like in PATH) by a colon on Unixish platforms and by a semicolon on Windows (the proper path separator being given by the command C<perl --V:path_sep>). +-V:I<path_sep>>). -When running taint checks (either because the program was running setuid -or setgid, or the B<-T> or B<-t> switch was specified), neither variable -is used. The program should instead say: +When running taint checks, either because the program was running setuid or +setgid, or the B<-T> or B<-t> switch was specified, neither PERL5LIB nor +PERLLIB is consulted. The program should instead say: use lib "/my/directory"; =item PERL5OPT X<PERL5OPT> -Command-line options (switches). Switches in this variable are taken +Command-line options (switches). Switches in this variable are treated as if they were on every Perl command line. Only the B<-[CDIMUdmtwW]> -switches are allowed. When running taint checks (because the program -was running setuid or setgid, or the B<-T> switch was used), this -variable is ignored. If PERL5OPT begins with B<-T>, tainting will be -enabled, and any subsequent options ignored. +switches are allowed. When running taint checks (either because the +program was running setuid or setgid, or because the B<-T> or B<-t> +switch was used), this variable is ignored. If PERL5OPT begins with +B<- T>, tainting will be enabled and subsequent options ignored. If +PERL5OPT begins with B<-t>, tainting will be enabled, a writable dot +removed from @INC, and subsequent options honored. =item PERLIO X<PERLIO> A space (or colon) separated list of PerlIO layers. If perl is built -to use PerlIO system for IO (the default) these layers effect perl's IO. +to use PerlIO system for IO (the default) these layers affect Perl's IO. -It is conventional to start layer names with a colon e.g. C<:perlio> to -emphasise their similarity to variable "attributes". But the code that parses -layer specification strings (which is also used to decode the PERLIO -environment variable) treats the colon as a separator. +It is conventional to start layer names with a colon (for example, C<:perlio>) to +emphasize their similarity to variable "attributes". But the code that parses +layer specification strings, which is also used to decode the PERLIO +environment variable, treats the colon as a separator. An unset or empty PERLIO is equivalent to the default set of layers for -your platform, for example C<:unix:perlio> on Unix-like systems +your platform; for example, C<:unix:perlio> on Unix-like systems and C<:unix:crlf> on Windows and other DOS-like systems. -The list becomes the default for I<all> perl's IO. Consequently only built-in -layers can appear in this list, as external layers (such as :encoding()) need +The list becomes the default for I<all> Perl's IO. Consequently only built-in +layers can appear in this list, as external layers (such as C<:encoding()>) need IO in order to load them!. See L<"open pragma"|open> for how to add external encodings as defaults. -The layers that it makes sense to include in the PERLIO environment -variable are briefly summarised below. For more details see L<PerlIO>. +Layers it makes sense to include in the PERLIO environment +variable are briefly summarized below. For more details see L<PerlIO>. =over 8 =item :bytes X<:bytes> -A pseudolayer that turns I<off> the C<:utf8> flag for the layer below. -Unlikely to be useful on its own in the global PERLIO environment variable. +A pseudolayer that turns the C<:utf8> flag I<off> for the layer below; +unlikely to be useful on its own in the global PERLIO environment variable. You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>. =item :crlf X<:crlf> -A layer which does CRLF to "\n" translation distinguishing "text" and +A layer which does CRLF to C<"\n"> translation distinguishing "text" and "binary" files in the manner of MS-DOS and similar operating systems. (It currently does I<not> mimic MS-DOS as far as treating of Control-Z as being an end-of-file marker.) @@ -1033,101 +1037,101 @@ as being an end-of-file marker.) =item :mmap X<:mmap> -A layer which implements "reading" of files by using C<mmap()> to -make (whole) file appear in the process's address space, and then +A layer that implements "reading" of files by using I<mmap>(2) to +make an entire file appear in the process's address space, and then using that as PerlIO's "buffer". =item :perlio X<:perlio> -This is a re-implementation of "stdio-like" buffering written as a -PerlIO "layer". As such it will call whatever layer is below it for -its operations (typically C<:unix>). +This is a re-implementation of stdio-like buffering written as a +PerlIO layer. As such it will call whatever layer is below it for +its operations, typically C<:unix>. =item :pop X<:pop> An experimental pseudolayer that removes the topmost layer. -Use with the same care as is reserved for nitroglycerin. +Use with the same care as is reserved for nitroglycerine. =item :raw X<:raw> A pseudolayer that manipulates other layers. Applying the C<:raw> layer is equivalent to calling C<binmode($fh)>. It makes the stream -pass each byte as-is without any translation. In particular CRLF -translation, and/or :utf8 intuited from locale are disabled. +pass each byte as-is without translation. In particular, both CRLF +translation and intuiting C<:utf8> from the locale are disabled. -Unlike in the earlier versions of Perl C<:raw> is I<not> -just the inverse of C<:crlf> - other layers which would affect the +Unlike in earlier versions of Perl, C<:raw> is I<not> +just the inverse of C<:crlf>: other layers which would affect the binary nature of the stream are also removed or disabled. =item :stdio X<:stdio> -This layer provides PerlIO interface by wrapping system's ANSI C "stdio" +This layer provides a PerlIO interface by wrapping system's ANSI C "stdio" library calls. The layer provides both buffering and IO. -Note that C<:stdio> layer does I<not> do CRLF translation even if that -is platforms normal behaviour. You will need a C<:crlf> layer above it +Note that the C<:stdio> layer does I<not> do CRLF translation even if that +is the platform's normal behaviour. You will need a C<:crlf> layer above it to do that. =item :unix X<:unix> -Low level layer which calls C<read>, C<write> and C<lseek> etc. +Low-level layer that calls C<read>, C<write>, C<lseek>, etc. =item :utf8 X<:utf8> -A pseudolayer that turns on a flag on the layer below to tell perl +A pseudolayer that enables a flag in the layer below to tell Perl that output should be in utf8 and that input should be regarded as -already in valid utf8 form. It does not check for validity and as such -should be handled with caution for input. Generally C<:encoding(utf8)> is +already in valid utf8 form. B<WARNING: It does not check for validity and as such +should be handled with extreme caution for input, because security violations +can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(utf8)> is the best option when reading UTF-8 encoded data. =item :win32 X<:win32> On Win32 platforms this I<experimental> layer uses native "handle" IO -rather than unix-like numeric file descriptor layer. Known to be -buggy in this release. +rather than a Unix-like numeric file descriptor layer. Known to be +buggy in this release (5.14). =back -On all platforms the default set of layers should give acceptable results. +The default set of layers should give acceptable results on all platforms -For Unix platforms that will equivalent of "unix perlio" or "stdio". -Configure is setup to prefer "stdio" implementation if system's library -provides for fast access to the buffer, otherwise it uses the "unix perlio" +For Unix platforms that will be the equivalent of "unix perlio" or "stdio". +Configure is set up to prefer the "stdio" implementation if the system's library +provides for fast access to the buffer; otherwise, it uses the "unix perlio" implementation. -On Win32 the default in this release is "unix crlf". Win32's "stdio" -has a number of bugs/mis-features for perl IO which are somewhat -C compiler vendor/version dependent. Using our own C<crlf> layer as -the buffer avoids those issues and makes things more uniform. -The C<crlf> layer provides CRLF to/from "\n" conversion as well as -buffering. +On Win32 the default in this release (5.14) is "unix crlf". Win32's "stdio" +has a number of bugs/mis-features for Perl IO which are somewhat depending +on the version and vendor of the C compiler. Using our own C<crlf> layer as +the buffer avoids those issues and makes things more uniform. The C<crlf> +layer provides CRLF conversion as well as buffering. -This release uses C<unix> as the bottom layer on Win32 and so still uses C -compiler's numeric file descriptor routines. There is an experimental native -C<win32> layer which is expected to be enhanced and should eventually be -the default under Win32. +This release (5.14) uses C<unix> as the bottom layer on Win32, and so still +uses the C compiler's numeric file descriptor routines. There is an +experimental native C<win32> layer, which is expected to be enhanced and +should eventually become the default under Win32. -The PERLIO environment variable is completely ignored when perl +The PERLIO environment variable is completely ignored when Perl is run in taint mode. =item PERLIO_DEBUG X<PERLIO_DEBUG> -If set to the name of a file or device then certain operations of PerlIO -sub-system will be logged to that file (opened as append). Typical uses -are Unix: +If set to the name of a file or device, certain operations of PerlIO +subsystem will be logged to that file, which is opened in append mode +Typical uses are in Unix: - PERLIO_DEBUG=/dev/tty perl script ... + % env PERLIO_DEBUG=/dev/tty perl script ... -and Win32 approximate equivalent: +and under Win32, the approximately equivalent: - set PERLIO_DEBUG=CON + > set PERLIO_DEBUG=CON perl script ... This functionality is disabled for setuid scripts and for scripts run @@ -1140,7 +1144,7 @@ A list of directories in which to look for Perl library files before looking in the standard library and the current directory. If PERL5LIB is defined, PERLLIB is not used. -The PERLLIB environment variable is completely ignored when perl +The PERLLIB environment variable is completely ignored when Perl is run in taint mode. =item PERL5DB @@ -1148,9 +1152,9 @@ X<PERL5DB> The command used to load the debugger code. The default is: - BEGIN { require 'perl5db.pl' } + BEGIN { require "perl5db.pl" } -The PERL5DB environment variable only used when perl is started with +The PERL5DB environment variable is only used when Perl is started with a bare B<-d> switch. =item PERL5DB_THREADED @@ -1162,15 +1166,15 @@ debugged uses threads. =item PERL5SHELL (specific to the Win32 port) X<PERL5SHELL> -May be set to an alternative shell that perl must use internally for -executing "backtick" commands or system(). Default is C<cmd.exe /x/d/c> -on WindowsNT and C<command.com /c> on Windows95. The value is considered -to be space-separated. Precede any character that needs to be protected -(like a space or backslash) with a backslash. +On Win32 ports only, may be set to an alternative shell that Perl must use +internally for executing "backtick" commands or system(). Default is +C<cmd.exe /x/d/c> on WindowsNT and C<command.com /c> on Windows95. The +value is considered space-separated. Precede any character that +needs to be protected, like a space or backslash, with another backslash. Note that Perl doesn't use COMSPEC for this purpose because COMSPEC has a high degree of variability among users, leading to -portability concerns. Besides, perl can use a shell that may not be +portability concerns. Besides, Perl can use a shell that may not be fit for interactive use, and setting COMSPEC to such a shell may interfere with the proper functioning of other programs (which usually look in COMSPEC to find a shell fit for interactive use). @@ -1183,73 +1187,75 @@ in taint mode under Windows. =item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port) X<PERL_ALLOW_NON_IFS_LSP> -Set to 1 to allow the use of non-IFS compatible LSP's. +Set to 1 to allow the use of non-IFS compatible LSPs (Layered Service Providers). Perl normally searches for an IFS-compatible LSP because this is required for its emulation of Windows sockets as real filehandles. However, this may -cause problems if you have a firewall such as McAfee Guardian which requires -all applications to use its LSP which is not IFS-compatible, because clearly +cause problems if you have a firewall such as I<McAfee Guardian>, which requires +that all applications use its LSP but which is not IFS-compatible, because clearly Perl will normally avoid using such an LSP. + Setting this environment variable to 1 means that Perl will simply use the -first suitable LSP enumerated in the catalog, which keeps McAfee Guardian -happy (and in that particular case Perl still works too because McAfee -Guardian's LSP actually plays some other games which allow applications -requiring IFS compatibility to work). +first suitable LSP enumerated in the catalog, which keeps I<McAfee Guardian> +happy--and in that particular case Perl still works too because I<McAfee +Guardian>'s LSP actually plays other games which allow applications +requiring IFS compatibility to work. =item PERL_DEBUG_MSTATS X<PERL_DEBUG_MSTATS> -Relevant only if perl is compiled with the malloc included with the perl -distribution (that is, if C<perl -V:d_mymalloc> is 'define'). -If set, this causes memory statistics to be dumped after execution. If set -to an integer greater than one, also causes memory statistics to be dumped +Relevant only if Perl is compiled with the C<malloc> included with the Perl +distribution; that is, if C<perl -V:d_mymalloc> is "define". + +If set, this dumps out memory statistics after execution. If set +to an integer greater than one, also dumps out memory statistics after compilation. =item PERL_DESTRUCT_LEVEL X<PERL_DESTRUCT_LEVEL> -Relevant only if your perl executable was built with B<-DDEBUGGING>, -this controls the behavior of global destruction of objects and other -references. See L<perlhack/PERL_DESTRUCT_LEVEL> for more information. +Relevant only if your Perl executable was built with B<-DDEBUGGING>, +this controls the behaviour of global destruction of objects and other +references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information. =item PERL_DL_NONLAZY X<PERL_DL_NONLAZY> -Set to one to have perl resolve B<all> undefined symbols when it loads +Set to C<"1"> to have Perl resolve I<all> undefined symbols when it loads a dynamic library. The default behaviour is to resolve symbols when they are used. Setting this variable is useful during testing of -extensions as it ensures that you get an error on misspelled function -names even if the test suite doesn't call it. +extensions, as it ensures that you get an error on misspelled function +names even if the test suite doesn't call them. =item PERL_ENCODING X<PERL_ENCODING> -If using the C<encoding> pragma without an explicit encoding name, the +If using the C<use encoding> pragma without an explicit encoding name, the PERL_ENCODING environment variable is consulted for an encoding name. =item PERL_HASH_SEED X<PERL_HASH_SEED> -(Since Perl 5.8.1.) Used to randomise perl's internal hash function. -To emulate the pre-5.8.1 behaviour, set to an integer (zero means -exactly the same order as 5.8.0). "Pre-5.8.1" means, among other +(Since Perl 5.8.1.) Used to randomize Perl's internal hash function. +To emulate the pre-5.8.1 behaviour, set to an integer; C<"0"> means +exactly the same order as in 5.8.0. "Pre-5.8.1" means, among other things, that hash keys will always have the same ordering between -different runs of perl. +different runs of Perl. -Most hashes return elements in the same order as Perl 5.8.0 by default. +Most hashes by default return elements in the same order as in Perl 5.8.0. On a hash by hash basis, if pathological data is detected during a hash key insertion, then that hash will switch to an alternative random hash seed. -The default behaviour is to randomise unless the PERL_HASH_SEED is set. -If perl has been compiled with C<-DUSE_HASH_SEED_EXPLICIT>, the default -behaviour is B<not> to randomise unless the PERL_HASH_SEED is set. +The default behaviour is to randomize unless the PERL_HASH_SEED is set. +If Perl has been compiled with B<-DUSE_HASH_SEED_EXPLICIT>, the default +behaviour is I<not> to randomize unless the PERL_HASH_SEED is set. -If PERL_HASH_SEED is unset or set to a non-numeric string, perl uses +If PERL_HASH_SEED is unset or set to a non-numeric string, Perl uses the pseudorandom seed supplied by the operating system and libraries. -B<Please note that the hash seed is sensitive information>. Hashes are +B<PLEASE NOTE: The hash seed is sensitive information>. Hashes are randomized to protect against local and remote attacks against Perl -code. By manually setting a seed this protection may be partially or +code. By manually setting a seed, this protection may be partially or completely lost. See L<perlsec/"Algorithmic Complexity Attacks"> and @@ -1258,48 +1264,48 @@ L</PERL_HASH_SEED_DEBUG> for more information. =item PERL_HASH_SEED_DEBUG X<PERL_HASH_SEED_DEBUG> -(Since Perl 5.8.1.) Set to one to display (to STDERR) the value of +(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) the value of the hash seed at the beginning of execution. This, combined with L</PERL_HASH_SEED> is intended to aid in debugging nondeterministic -behavior caused by hash randomization. +behaviour caused by hash randomization. -B<Note that the hash seed is sensitive information>: by knowing it one -can craft a denial-of-service attack against Perl code, even remotely, +B<Note that the hash seed is sensitive information>: by knowing it, one +can craft a denial-of-service attack against Perl code, even remotely; see L<perlsec/"Algorithmic Complexity Attacks"> for more information. B<Do not disclose the hash seed> to people who don't need to know it. -See also hash_seed() of L<Hash::Util>. +See also hash_seed() in L<Hash::Util>. =item PERL_MEM_LOG X<PERL_MEM_LOG> -If your perl was configured with C<-Accflags=-DPERL_MEM_LOG>, setting +If your Perl was configured with B<-Accflags=-DPERL_MEM_LOG>, setting the environment variable C<PERL_MEM_LOG> enables logging debug -messages. The value has the form C<< <number>[m][s][t] >>, where -C<number> is the filedescriptor number you want to write to (2 is +messages. The value has the form C<< <I<number>>[m][s][t] >>, where +C<I<number>> is the file descriptor number you want to write to (2 is default), and the combination of letters specifies that you want information about (m)emory and/or (s)v, optionally with -(t)imestamps. For example C<PERL_MEM_LOG=1mst> will log all -information to stdout. You can write to other opened filedescriptors -too, in a variety of ways; +(t)imestamps. For example, C<PERL_MEM_LOG=1mst> logs all +information to stdout. You can write to other opened file descriptors +in a variety of ways: - bash$ 3>foo3 PERL_MEM_LOG=3m perl ... + $ 3>foo3 PERL_MEM_LOG=3m perl ... =item PERL_ROOT (specific to the VMS port) X<PERL_ROOT> -A translation concealed rooted logical name that contains perl and the +A translation-concealed rooted logical name that contains Perl and the logical device for the @INC path on VMS only. Other logical names that -affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and -SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in +affect Perl on VMS include PERLSHR, PERL_ENV_TABLES, and +SYS$TIMEZONE_DIFFERENTIAL, but are optional and discussed further in L<perlvms> and in F<README.vms> in the Perl source distribution. =item PERL_SIGNALS X<PERL_SIGNALS> -In Perls 5.8.1 and later. If set to C<unsafe> the pre-Perl-5.8.0 -signals behaviour (immediate but unsafe) is restored. If set to -C<safe> the safe (or deferred) signals are used. -See L<perlipc/"Deferred Signals (Safe Signals)">. +Available in Perls 5.8.1 and later. If set to C<"unsafe">, the pre-Perl-5.8.0 +signal behaviour (which is immediate but unsafe) is restored. If set +to C<safe>, then safe (but deferred) signals are used. See +L<perlipc/"Deferred Signals (Safe Signals)">. =item PERL_UNICODE X<PERL_UNICODE> @@ -1308,7 +1314,7 @@ Equivalent to the B<-C> command-line switch. Note that this is not a boolean variable. Setting this to C<"1"> is not the right way to "enable Unicode" (whatever that would mean). You can use C<"0"> to "disable Unicode", though (or alternatively unset PERL_UNICODE in -your shell before starting Perl). See the description of the C<-C> +your shell before starting Perl). See the description of the B<-C> switch for more information. =item SYS$LOGIN (specific to the VMS port) @@ -1319,14 +1325,20 @@ Used if chdir has no argument and HOME and LOGDIR are not set. =back Perl also has environment variables that control how Perl handles data -specific to particular natural languages. See L<perllocale>. - -Apart from these, Perl uses no other environment variables, except -to make them available to the program being executed, and to child -processes. However, programs running setuid would do well to execute -the following lines before doing anything else, just to keep people -honest: - - $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need - $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL}; +specific to particular natural languages; see L<perllocale>. + +Perl and its various modules and components, including its test frameworks, +may sometimes make use of certain other environment variables. Some of +these are specific to a particular platform. Please consult the +appropriate module documentation and any documentation for your platform +(like L<perlsolaris>, L<perllinux>, L<perlmacosx>, L<perlwin32>, etc) for +variables peculiar to those specific situations. + +Perl makes all environment variables available to the program being +executed, and passes these along to any child processes it starts. +However, programs running setuid would do well to execute the following +lines before doing anything else, just to keep people honest: + + $ENV{PATH} = "/bin:/usr/bin"; # or whatever you need + $ENV{SHELL} = "/bin/sh" if exists $ENV{SHELL}; delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; diff --git a/Master/tlpkg/tlperl/lib/pods/perlsolaris.pod b/Master/tlpkg/tlperl/lib/pods/perlsolaris.pod index 427e08de6ed..b8c8dbf71e4 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlsolaris.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlsolaris.pod @@ -18,7 +18,7 @@ For the most part, everything should just work. Starting with Solaris 8, perl5.00503 (or higher) is supplied with the operating system, so you might not even need to build a newer version of perl at all. The Sun-supplied version is installed in /usr/perl5 -with /usr/bin/perl pointing to /usr/perl5/bin/perl. Do not disturb +with F</usr/bin/perl> pointing to F</usr/perl5/bin/perl>. Do not disturb that installation unless you really know what you are doing. If you remove the perl supplied with the OS, you will render some bits of your system inoperable. If you wish to install a newer version of perl, @@ -26,9 +26,9 @@ install it under a different prefix from /usr/perl5. Common prefixes to use are /usr/local and /opt/perl. You may wish to put your version of perl in the PATH of all users by -changing the link /usr/bin/perl. This is probably OK, as most perl +changing the link F</usr/bin/perl>. This is probably OK, as most perl scripts shipped with Solaris use an explicit path. (There are a few -exceptions, such as /usr/bin/rpm2cpio and /etc/rcm/scripts/README, but +exceptions, such as F</usr/bin/rpm2cpio> and F</etc/rcm/scripts/README>, but these are also sufficiently generic that the actual version of perl probably doesn't matter too much.) @@ -39,7 +39,7 @@ these modules is available on CPAN under the Sun::Solaris:: namespace. Solaris may include two versions of perl, e.g. Solaris 9 includes both 5.005_03 and 5.6.1. This is to provide stability across Solaris releases, in cases where a later perl version has incompatibilities -with the version included in the preceeding Solaris release. The +with the version included in the preceding Solaris release. The default perl version will always be the most recent, and in general the old version will only be retained for one Solaris release. Note also that the default perl will NOT be configured to search for modules @@ -143,18 +143,25 @@ shipped with SunOS4 will not do. Several tools needed to build perl are located in /usr/ccs/bin/: ar, as, ld, and make. Make sure that /usr/ccs/bin/ is in your PATH. -You need to make sure the following packages are installed -(this info is extracted from the Solaris FAQ): + +On all the released versions of Solaris (8, 9 and 10) you need to make sure the following packages are installed (this info is extracted from the Solaris FAQ): for tools (sccs, lex, yacc, make, nm, truss, ld, as): SUNWbtool, SUNWsprot, SUNWtoo for libraries & headers: SUNWhea, SUNWarc, SUNWlibm, SUNWlibms, SUNWdfbh, -SUNWcg6h, SUNWxwinc, SUNWolinc +SUNWcg6h, SUNWxwinc + +Additionaly, on Solaris 8 and 9 you also need: for 64 bit development: SUNWarcx, SUNWbtoox, SUNWdplx, SUNWscpux, SUNWsprox, SUNWtoox, SUNWlmsx, SUNWlmx, SUNWlibCx +And only on Solaris 8 you also need: + +for libraries & headers: SUNWolinc + + If you are in doubt which package contains a file you are missing, try to find an installation that has that file. Then do a @@ -213,7 +220,7 @@ details. =head3 GNU as and GNU ld The following information applies to gcc version 2. Volunteers to -update it as appropropriate for gcc version 3 would be appreciated. +update it as appropriately for gcc version 3 would be appreciated. The versions of as and ld supplied with Solaris work fine for building perl. There is normally no need to install the GNU versions to @@ -514,7 +521,7 @@ directory. =head2 op/stat.t test 4 in Solaris -op/stat.t test 4 may fail if you are on a tmpfs of some sort. +F<op/stat.t> test 4 may fail if you are on a tmpfs of some sort. Building in /tmp sometimes shows this behavior. The test suite detects if you are building in /tmp, but it may not be able to catch all tmpfs situations. @@ -594,7 +601,7 @@ L<http://www.cosy.sbg.ac.at/~andi/>. If you use SUNWski, make a symbolic link /dev/urandom pointing to /dev/random. For more details, see Document ID27606 entitled "Differing /dev/random support requirements within Solaris[TM] Operating Environments", available at -http://sunsolve.sun.com . +L<http://sunsolve.sun.com> . It may be possible to use the Entropy Gathering Daemon (written in Perl!), available from L<http://www.lothar.com/tech/crypto/>. @@ -609,7 +616,7 @@ GNU ld gets very unhappy and spews a lot of errors like this ... relocation truncated to fit: BASE13 ... and dies. Therefore the SunOS 4.1 hints file explicitly sets the -ld to be /usr/bin/ld. +ld to be F</usr/bin/ld>. As of Perl 5.8.1 the dynamic loading of libraries (DynaLoader, XSLoader) also seems to have become broken in in SunOS 4.x. Therefore the default diff --git a/Master/tlpkg/tlperl/lib/pods/perlsource.pod b/Master/tlpkg/tlperl/lib/pods/perlsource.pod new file mode 100644 index 00000000000..94ceec00bd3 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perlsource.pod @@ -0,0 +1,216 @@ +=encoding utf8 + +=for comment +Consistent formatting of this file is achieved with: + perl ./Porting/podtidy pod/perlsource.pod + +=head1 NAME + +perlsource - A guide to the Perl source tree + +=head1 DESCRIPTION + +This document describes the layout of the Perl source tree. If you're hacking +on the Perl core, this will help you find what you're looking for. + +=head1 FINDING YOUR WAY AROUND + +The Perl source tree is big. Here's some of the thing you'll find in it: + +=head2 C code + +The C source code and header files mostly live in the root of the source +tree. There are a few platform-specific directories which contain C code. In +addition, some of the modules shipped with Perl include C or XS code. + +See L<perlinterp> for more details on the files that make up the Perl +interpreter, as well as details on how it works. + +=head2 Core modules + +Modules shipped as part of the Perl core live in four subdirectories. Two of +these directories contain modules that live in the core, and two contain +modules that can also be released separately on CPAN. Modules which can be +released on cpan are known as "dual-life" modules. + +=over 4 + +=item * F<lib/> + +This directory contains pure-Perl modules which are only released as part of +the core. This directory contains I<all> of the modules and their tests, +unlike other core modules. + +=item * F<ext/> + +This directory contains XS-using modules which are only released as part of +the core. These modules generally have their F<Makefile.PL> and are laid out +more like a typical CPAN module. + +=item * F<dist/> + +This directory is for dual-life modules where the blead source is +canonical. Note that some modules in this directory may not yet have been +released separately on CPAN. + +=item * F<cpan/> + +This directory contains dual-life modules where the CPAN module is +canonical. Do not patch these modules directly! Changes to these modules +should be submitted to the maintainer of the CPAN module. Once those changes +are applied and released, the new version of the module will be incorporated +into the core. + +=back + +For some dual-life modules, it has not yet been determined if the CPAN version +or the blead source is canonical. Until that is done, those modules should be +in F<cpan/>. + +=head2 Tests + +The Perl core has an extensive test suite. If you add new tests (or new +modules with tests), you may need to update the F<t/TEST> file so that the +tests are run. + +=over 4 + +=item * Module tests + +Tests for core modules in the F<lib/> directory are right next to the module +itself. For example, we have F<lib/strict.pm> and F<lib/strict.t>. + +Tests for modules in F<ext/> and the dual-life modules are in F<t/> +subdirectories for each module, like a standard CPAN distribution. + +=item * F<t/base/> + +Tests for the absolute basic functionality of Perl. This includes C<if>, basic +file reads and writes, simple regexes, etc. These are run first in the test +suite and if any of them fail, something is I<really> broken. + +=item * F<t/cmd/> + +Tests for basic control structures, C<if/else>, C<while>, +subroutines, etc. + +=item * F<t/comp/> + +Tests for basic issues of how Perl parses and compiles itself. + +=item * F<t/io/> + +Tests for built-in IO functions, including command line arguments. + +=item * F<t/mro/> + +Tests for perl's method resolution order implementations (see L<mro>). + +=item * F<t/op/> + +Tests for perl's built in functions that don't fit into any of the +other directories. + +=item * F<t/re/> + +Tests for regex related functions or behaviour. (These used to live in +t/op). + +=item * F<t/run/> + +Tests for features of how perl actually runs, including exit codes and +handling of PERL* environment variables. + +=item * F<t/uni/> + +Tests for the core support of Unicode. + +=item * F<t/win32/> + +Windows-specific tests. + +=item * F<t/porting/> + +Tests the state of the source tree for various common errors. For example, it +tests that everyone who is listed in the git log has a corresponding entry in +the F<AUTHORS> file. + +=item * F<t/lib/> + +The old home for the module tests, you shouldn't put anything new in +here. There are still some bits and pieces hanging around in here that +need to be moved. Perhaps you could move them? Thanks! + +=item * F<t/x2p> + +A test suite for the s2p converter. + +=back + +=head2 Documentation + +All of the core documentation intended for end users lives in +F<pod/>. Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/> +usually have their own documentation, either in the F<Module.pm> file or an +accompanying F<Module.pod> file. + +Finally, documentation intended for core Perl developers lives in the +F<Porting/> directory. + +=head2 Hacking toolks and documentation + +The F<Porting> directory contains a grab bag of code and documentation +intended to help porters work on Perl. Some of the highlights include: + +=over 4 + +=item * F<check*> + +These are scripts which will check the source things like ANSI C violations, +POD encoding issues, etc. + +=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm> + +These files contain information on who maintains which modules. Run C<perl +Porting/Maintainers -M Module::Name> to find out more information about a +dual-life module. + +=item * F<podtidy> + +Tidies a pod file. It's a good idea to run this on a pod file you've patched. + +=back + +=head2 Build system + +The Perl build system starts with the F<Configure> script in the root +directory. + +Platform-specific pieces of the build system also live in platform-specific +directories like F<win32/>, F<vms/>, etc. + +The F<Configure> script is ultimately responsible for generating a +F<Makefile>. + +The build system that Perl uses is called metaconfig. This system is +maintained separately from the Perl core. + +The metaconfig system has its own git repository. Please see its README file +in L<http://perl5.git.perl.org/metaconfig.git/> for more details. + +The F<Cross> directory contains various files related to cross-compiling +Perl. See F<Cross/README> for more details. + +=head2 F<AUTHORS> + +This file everyone who's contributed to Perl. If you submit a patch, you +should add your name to this file as part of the patch. + +=head2 F<MANIFEST> + +The F<MANIFEST> file in the root of the source tree contains a list of every +file in the Perl core, as well as a brief description of each file. + +You can get an overview of all the files with this command: + + % perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST diff --git a/Master/tlpkg/tlperl/lib/pods/perlsub.pod b/Master/tlpkg/tlperl/lib/pods/perlsub.pod index 325c823bff4..ea5fa207cc8 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlsub.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlsub.pod @@ -351,7 +351,7 @@ it. Similarly, in the conditional the scope of $answer extends from its declaration through the rest of that conditional, including any C<elsif> and C<else> clauses, -but not beyond it. See L<perlsyn/"Simple statements"> for information +but not beyond it. See L<perlsyn/"Simple Statements"> for information on the scope of variables in statements with modifiers. The C<foreach> loop defaults to scoping its index variable dynamically @@ -608,16 +608,9 @@ magical and read-only : local $1 = 2; -Similarly, but in a way more difficult to spot, the following snippet will -die in perl 5.9.0 : - - sub f { local $_ = "foo"; print } - for ($1) { - # now $_ is aliased to $1, thus is magic and readonly - f(); - } - -See next section for an alternative to this situation. +One exception is the default scalar variable: starting with perl 5.14 +C<local($_)> will always strip all magic from $_, to make it possible +to safely reuse $_ in a subroutine. B<WARNING>: Localization of tied arrays and hashes does not currently work as described. @@ -644,12 +637,6 @@ those variables is locally lost. In other words, saying C<local */> will not have any effect on the internal value of the input record separator. -Notably, if you want to work with a brand new value of the default scalar -$_, and avoid the potential problem listed above about $_ previously -carrying a magic value, you should use C<local *_> instead of C<local $_>. -As of perl 5.9.1, you can also use the lexical form of C<$_> (declaring it -with C<my $_>), which avoids completely this problem. - =head3 Localization of elements of composite types X<local, composite type element> X<local, array element> X<local, hash element> @@ -1053,7 +1040,7 @@ X<prototype> X<subroutine, prototype> Perl supports a very limited kind of compile-time argument checking using function prototyping. If you declare - sub mypush (\@@) + sub mypush (+@) then C<mypush()> takes arguments exactly like C<push()> does. The function declaration must be visible at compile time. The prototype @@ -1083,9 +1070,9 @@ corresponding built-in. sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off sub myreverse (@) myreverse $a, $b, $c sub myjoin ($@) myjoin ":", $a, $b, $c - sub mypop (\@) mypop @array - sub mysplice (\@$$@) mysplice @array, 0, 2, @pushme - sub mykeys (\%) mykeys %{$hashref} + sub mypop (+) mypop @array + sub mysplice (+$$@) mysplice @array, 0, 2, @pushme + sub mykeys (+) mykeys %{$hashref} sub myopen (*;$) myopen HANDLE, $name sub mypipe (**) mypipe READHANDLE, WRITEHANDLE sub mygrep (&@) mygrep { /foo/ } $a, $b, $c @@ -1093,12 +1080,15 @@ corresponding built-in. sub mytime () mytime Any backslashed prototype character represents an actual argument -that absolutely must start with that character. The value passed -as part of C<@_> will be a reference to the actual argument given -in the subroutine call, obtained by applying C<\> to that argument. +that must start with that character (optionally preceded by C<my>, +C<our> or C<local>), with the exception of C<$>, which will accept a +hash or array element even without a dollar sign, such as +C<< my_function()->[0] >>. The value passed as part of C<@_> will be a +reference to the actual argument given in the subroutine call, +obtained by applying C<\> to that argument. -You can also backslash several argument types simultaneously by using -the C<\[]> notation: +You can use the C<\[]> backslash group notation to specify more than one +allowed argument type. For example: sub myref (\[$@%&*]) @@ -1133,6 +1123,20 @@ follows: ... } +The C<+> prototype is a special alternative to C<$> that will act like +C<\[@%]> when given a literal array or hash variable, but will otherwise +force scalar context on the argument. This is useful for functions which +should accept either a literal array or an array reference as the argument: + + sub mypush (+@) { + my $aref = shift; + die "Not an array or arrayref" unless ref $aref eq 'ARRAY'; + push @$aref, @_; + } + +When using the C<+> prototype, your function must check that the argument +is of an acceptable type. + A semicolon (C<;>) separates mandatory arguments from optional arguments. It is redundant before C<@> or C<%>, which gobble up everything else. @@ -1425,7 +1429,11 @@ of the original subroutine magically appears in the global $AUTOLOAD variable of the same package as the C<AUTOLOAD> routine. The name is not passed as an ordinary argument because, er, well, just because, that's why. (As an exception, a method call to a nonexistent -C<import> or C<unimport> method is just skipped instead.) +C<import> or C<unimport> method is just skipped instead. Also, if +the AUTOLOAD subroutine is an XSUB, C<$AUTOLOAD> is not populated; +instead, you should call L<< C<SvPVX>E<sol>C<SvCUR>|perlapi >> on the +C<CV> for C<AUTOLOAD> to retrieve the method name.) + Many C<AUTOLOAD> routines load in a definition for the requested subroutine using eval(), then execute that subroutine using a special diff --git a/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod b/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod index 341c0269fb5..04678fe8f55 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlsymbian.pod @@ -33,11 +33,11 @@ mainly as demonstrations. These instructions have been tested under various Nokia Series 60 Symbian SDKs (1.2 to 2.6, 2.8 should also work, 1.2 compiles but does not work), Series 80 2.0, and Nokia 7710 (Series 90) SDK. - You can get the SDKs from Forum Nokia (http://www.forum.nokia.com/). + You can get the SDKs from Forum Nokia (L<http://www.forum.nokia.com/>). A very rough port ("it compiles") to UIQ 2.1 has also been made. A prerequisite for any of the SDKs is to install ActivePerl - from ActiveState, http://www.activestate.com/Products/ActivePerl/ + from ActiveState, L<http://www.activestate.com/Products/ActivePerl/> Having the SDK installed also means that you need to have either the Metrowerks CodeWarrior installed (2.8 and 3.0 were used in testing) @@ -57,7 +57,7 @@ mainly as demonstrations. releases, SDKs, compilers, platforms, or devices are naturally welcome. (1) Get a Perl source code distribution (for example the file - perl-5.9.2.tar.gz is fine) from http://www.cpan.org/src/ + perl-5.9.2.tar.gz is fine) from L<http://www.cpan.org/src/> and unpack it in your the C:/Symbian directory of your Windows system. @@ -215,7 +215,7 @@ If you see right after "make" this 'cat' is not recognized as an internal or external command, operable program or batch file. -it means you need to (re)run the symbian\config.pl. +it means you need to (re)run the F<symbian\config.pl>. If you get the error @@ -243,19 +243,19 @@ the "Oneliner" allows one to type in Perl code, and the "Run" opens a file chooser for selecting a Perl file to run. The PerlApp also is started when the "Perl recognizer" (also included -and installed) detects a Perl file being activated througg the GUI, +and installed) detects a Perl file being activated through the GUI, and offers either to install it under \Perl (if the Perl file is in the inbox of the messaging application) or to run it (if the Perl file is under \Perl). =head2 sisify.pl -In the symbian subdirectory there is sisify.pl utility which can be -used to package Perl scripts and/or Perl library directories into SIS -files, which can be installed to the device. To run the sisify.pl -utility, you will need to have the 'makesis' and 'uidcrc' utilities -already installed. If you don't have the Win32 SDKs, you may try -for example http://gnupoc.sourceforge.net/ or http://symbianos.org/~andreh/. +In the symbian subdirectory there is F<sisify.pl> utility which can be used +to package Perl scripts and/or Perl library directories into SIS files, +which can be installed to the device. To run the sisify.pl utility, +you will need to have the 'makesis' and 'uidcrc' utilities already +installed. If you don't have the Win32 SDKs, you may try for example +L<http://gnupoc.sourceforge.net/> or L<http://symbianos.org/~andreh/>. =head2 Using Perl in Symbian @@ -270,9 +270,9 @@ library, but certain corners of such emulation libraries that tend to be left unimplemented on non-UNIX platforms have been left unimplemented also this time: fork(), signals(), user/group ids, select() working for sockets, non-blocking sockets, and so forth. -See the file symbian/config.sh and look for 'undef' to find the +See the file F<symbian/config.sh> and look for 'undef' to find the unsupported APIs (or from Perl use Config). - + The filesystem of Symbian devices uses DOSish syntax, "drives" separated from paths by a colon, and backslashes for the path. The exact assignment of the drives probably varies between platforms, but @@ -319,7 +319,7 @@ the API names. Instead, developers should consider basing the API naming in the existing (C++, or maybe Java) public component and API naming, modified as appropriate by the rules of the programming language the new APIs are for. - + Nokia is a registered trademark of Nokia Corporation. Nokia's product names are trademarks or registered trademarks of Nokia. Other product and company names mentioned herein may be trademarks or trade names of @@ -430,4 +430,3 @@ We maintain the binary incompatibility. =back =cut - diff --git a/Master/tlpkg/tlperl/lib/pods/perlsyn.pod b/Master/tlpkg/tlperl/lib/pods/perlsyn.pod index 6359df4e141..603dd15ae83 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlsyn.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlsyn.pod @@ -281,7 +281,7 @@ the C<next> statement. Extension modules can also hook into the Perl parser to define new kinds of compound statement. These are introduced by a keyword which -the extension recognises, and the syntax following the keyword is +the extension recognizes, and the syntax following the keyword is defined entirely by the extension. If you are an implementor, see L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such a module, see the module's documentation for details of the syntax that @@ -337,17 +337,17 @@ which is Perl short-hand for the more explicitly written version: Note that if there were a C<continue> block on the above code, it would get executed only on lines discarded by the regex (since redo skips the continue block). A continue block is often used to reset line counters -or C<?pat?> one-time matches: +or C<m?pat?> one-time matches: # inspired by :1,$g/fred/s//WILMA/ while (<>) { - ?(fred)? && s//WILMA $1 WILMA/; - ?(barney)? && s//BETTY $1 BETTY/; - ?(homer)? && s//MARGE $1 MARGE/; + m?(fred)? && s//WILMA $1 WILMA/; + m?(barney)? && s//BETTY $1 BETTY/; + m?(homer)? && s//MARGE $1 MARGE/; } continue { print "$ARGV $.: $_"; - close ARGV if eof(); # reset $. - reset if eof(); # reset ?pat? + close ARGV if eof; # reset $. + reset if eof; # reset ?pat? } If the word C<while> is replaced by the word C<until>, the sense of the @@ -426,7 +426,7 @@ is therefore visible only within the loop. Otherwise, the variable is implicitly local to the loop and regains its former value upon exiting the loop. If the variable was previously declared with C<my>, it uses that variable instead of the global one, but it's still localized to -the loop. This implicit localisation occurs I<only> in a C<foreach> +the loop. This implicit localization occurs I<only> in a C<foreach> loop. X<my> X<local> @@ -626,29 +626,71 @@ the C<..> and C<...> flip-flop operators. In those cases the value of EXPR is used directly as a boolean. -Furthermore: +Furthermore, Perl inspects the operands of the binary boolean operators to +decide whether to use smart matching for each one by applying the above test to +the operands: =over 4 =item * If EXPR is C<... && ...> or C<... and ...>, the test -is applied recursively to both arguments. If I<both> -arguments pass the test, then the argument is treated -as boolean. +is applied recursively to both operands. If I<both> +operands pass the test, then the expression is treated +as boolean; otherwise, smart matching is used. =item * If EXPR is C<... || ...>, C<... // ...> or C<... or ...>, the test -is applied recursively to the first argument. +is applied recursively to the first operand (which may be a +higher-precedence AND operator, for example). If the first operand +is to use smart matching, then both operands will do so; if it is +not, then the second argument will not be either. =back These rules look complicated, but usually they will do what -you want. For example you could write: +you want. For example: when (/^\d+$/ && $_ < 75) { ... } +will be treated as a boolean match because the rules say both a regex match and +an explicit test on $_ will be treated as boolean. + +Also: + + when ([qw(foo bar)] && /baz/) { ... } + +will use smart matching because only I<one> of the operands is a boolean; the +other uses smart matching, and that wins. + +Further: + + when ([qw(foo bar)] || /^baz/) { ... } + +will use smart matching (only the first operand is considered), whereas + + when (/^baz/ || [qw(foo bar)]) { ... } + +will test only the regex, which causes both operands to be treated as boolean. +Watch out for this one, then, because an arrayref is always a true value, which +makes it effectively redundant. + +Tautologous boolean operators are still going to be optimized away. Don't be +tempted to write + + when ('foo' or 'bar') { ... } + +This will optimize down to C<'foo'>, so C<'bar'> will never be considered (even +though the rules say to use a smart match on C<'foo'>). For an alternation like +this, an array ref will work, because this will instigate smart matching: + + when ([qw(foo bar)] { ... } + +This is somewhat equivalent to the C-style switch statement's fallthrough +functionality (not to be confused with I<Perl's> fallthrough functionality - see +below), wherein the same block is used for several C<case> statements. + Another useful shortcut is that, if you use a literal array or hash as the argument to C<given>, it is turned into a reference. So C<given(@foo)> is the same as C<given(\@foo)>, @@ -674,6 +716,45 @@ case to the next: default { say '$foo does not contain a y' } } +=head3 Return value + +When a C<given> statement is also a valid expression (e.g. +when it's the last statement of a block), it evaluates to : + +=over 4 + +=item * + +an empty list as soon as an explicit C<break> is encountered. + +=item * + +the value of the last evaluated expression of the successful +C<when>/C<default> clause, if there's one. + +=item * + +the value of the last evaluated expression of the C<given> block if no +condition is true. + +=back + +In both last cases, the last expression is evaluated in the context that +was applied to the C<given> block. + +Note that, unlike C<if> and C<unless>, failed C<when> statements always +evaluate to an empty list. + + my $price = do { given ($item) { + when ([ 'pear', 'apple' ]) { 1 } + break when 'vote'; # My vote cannot be bought + 1e10 when /Mona Lisa/; + 'unknown'; + } }; + +Currently, C<given> blocks can't always be used as proper expressions. This +may be addressed in a future version of perl. + =head3 Switching in a loop Instead of using C<given()>, you can use a C<foreach()> loop. @@ -886,17 +967,18 @@ X<comment> X<line> X<#> X<preprocessor> X<eval> Perl can process line directives, much like the C preprocessor. Using this, one can control Perl's idea of filenames and line numbers in error or warning messages (especially for strings that are processed -with C<eval()>). The syntax for this mechanism is the same as for most -C preprocessors: it matches the regular expression +with C<eval()>). The syntax for this mechanism is almost the same as for +most C preprocessors: it matches the regular expression # example: '# line 42 "new_filename.plx"' /^\# \s* line \s+ (\d+) \s* - (?:\s("?)([^"]+)\2)? \s* + (?:\s("?)([^"]+)\g2)? \s* $/x with C<$1> being the line number for the next line, and C<$3> being -the optional filename (specified with or without quotes). +the optional filename (specified with or without quotes). Note that +no whitespace may precede the C<< # >>, unlike modern C preprocessors. There is a fairly obvious gotcha included with the line directive: Debuggers and profilers will only show the last source line to appear diff --git a/Master/tlpkg/tlperl/lib/pods/perlthrtut.pod b/Master/tlpkg/tlperl/lib/pods/perlthrtut.pod index 18a6f46daa2..30f83577482 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlthrtut.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlthrtut.pod @@ -1,3 +1,5 @@ +=encoding utf8 + =head1 NAME perlthrtut - Tutorial on threads in Perl @@ -1078,13 +1080,13 @@ on your way to becoming a threaded Perl expert. Annotated POD for L<threads>: L<http://annocpan.org/?mode=search&field=Module&name=threads> -Lastest version of L<threads> on CPAN: +Latest version of L<threads> on CPAN: L<http://search.cpan.org/search?module=threads> Annotated POD for L<threads::shared>: L<http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared> -Lastest version of L<threads::shared> on CPAN: +Latest version of L<threads::shared> on CPAN: L<http://search.cpan.org/search?module=threads%3A%3Ashared> Perl threads mailing list: diff --git a/Master/tlpkg/tlperl/lib/pods/perltie.pod b/Master/tlpkg/tlperl/lib/pods/perltie.pod index 370f644209d..456cc60cbab 100644 --- a/Master/tlpkg/tlperl/lib/pods/perltie.pod +++ b/Master/tlpkg/tlperl/lib/pods/perltie.pod @@ -673,9 +673,9 @@ method on the original object reference returned by tie(). croak "@{[&whowasi]}: $file not clobberable" unless $self->{CLOBBER}; - open(F, "> $file") || croak "can't open $file: $!"; - print F $value; - close(F); + open(my $f, '>', $file) || croak "can't open $file: $!"; + print $f $value; + close($f); } If they wanted to clobber something, they might say: @@ -869,6 +869,13 @@ All of this is especially useful when perl is embedded in some other program, where output to STDOUT and STDERR may have to be redirected in some special way. See nvi and the Apache module for examples. +When tying a handle, the first argument to C<tie> should begin with an +asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have assigned +it to a scalar variable, say C<$handle>, use C<*$handle>. C<tie $handle> +works, too, but that is considered a bug and will be fixed in Perl 5.16. It +is supposed to tie the scalar C<$handle>, not the handle inside it. +C<tie $handle> emits a deprecation warning as of Perl 5.14. + In our example we're going to create a shouting handle. package Shout; @@ -940,10 +947,25 @@ or C<sysread> functions. =item READLINE this X<READLINE> -This method will be called when the handle is read from via <HANDLE>. -The method should return undef when there is no more data. - - sub READLINE { $r = shift; "READLINE called $$r times\n"; } +This method is called when the handle is read via C<E<lt>HANDLEE<gt>> +or C<readline HANDLE>. + +As per L<C<readline>|perlfunc/readline>, in scalar context it should return +the next line, or C<undef> for no more data. In list context it should +return all remaining lines, or an empty list for no more data. The strings +returned should include the input record separator C<$/> (see L<perlvar>), +unless it is C<undef> (which means "slurp" mode). + + sub READLINE { + my $r = shift; + if (wantarray) { + return ("all remaining\n", + "lines up\n", + "to eof\n"); + } else { + return "READLINE called " . ++$$r . " times\n"; + } + } =item GETC this X<GETC> diff --git a/Master/tlpkg/tlperl/lib/pods/perltoc.pod b/Master/tlpkg/tlperl/lib/pods/perltoc.pod index f1bd988bf30..a72f910d4dc 100644 --- a/Master/tlpkg/tlperl/lib/pods/perltoc.pod +++ b/Master/tlpkg/tlperl/lib/pods/perltoc.pod @@ -15,7 +15,7 @@ through to locate the proper section you're looking for. =head1 BASIC DOCUMENTATION -=head2 perl - The Perl language interpreter +=head2 perl - The Perl 5 language interpreter =over 4 @@ -623,7 +623,7 @@ X<record> X<structure> X<struct> =back -=head2 perlbot - Bag'o Object Tricks (the BOT) +=head2 perlbot - Bag o' Object Tricks (the BOT) =over 4 @@ -969,7 +969,7 @@ Interaction, perlfaq9 - Networking =over 4 -=item DESCRIPTION +=item DESCRIPTION =over 4 @@ -1023,7 +1023,7 @@ http://www.perl.org/advocacy/whyperl.html =over 4 -=item What machines support perl? Where do I get it? +=item What machines support perl? Where do I get it? =item How can I get a binary version of perl? @@ -1033,23 +1033,21 @@ http://www.perl.org/advocacy/whyperl.html don't work. =item I grabbed the sources and tried to compile but gdbm/dynamic -loading/malloc/linking/... failed. How do I make it work? +loading/malloc/linking/... failed. How do I make it work? -=item What modules and extensions are available for Perl? What is CPAN? +=item What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? =item Is there an ISO or ANSI certified version of Perl? =item Where can I get information on Perl? -=item What are the Perl newsgroups on Usenet? Where do I post questions? +=item What are the Perl newsgroups on Usenet? Where do I post questions? =item Where should I post source code? =item Perl Books -References, Tutorials, Task-Oriented, Special Topics - =item Which magazines have Perl content? =item What mailing lists are there for Perl? @@ -1249,7 +1247,7 @@ string? =item How do I capitalize all the words on one line? X<Text::Autoformat> X<capitalize> X<case, title> X<case, sentence> -=item How can I split a [character] delimited string except when inside +=item How can I split a [character]-delimited string except when inside [character]? =item How do I strip blank space from the beginning/end of a string? @@ -1267,8 +1265,9 @@ X<Text::Autoformat> X<capitalize> X<case, title> X<case, sentence> =item Why don't my E<lt>E<lt>HERE documents work? There must be no space after the E<lt>E<lt> part, There (probably) should -be a semicolon at the end, You can't (easily) have any space in front of -the tag +be a semicolon at the end of the opening token, You can't (easily) have any +space in front of the tag, There needs to be at least a line separator +after the end token =back @@ -1305,7 +1304,7 @@ X<cycle> X<modulus> =item How do I select a random element from an array? =item How do I permute N elements of a list? -X<List::Permuter> X<permute> X<Algorithm::Loops> X<Knuth> +X<List::Permutor> X<permute> X<Algorithm::Loops> X<Knuth> X<The Art of Computer Programming> X<Fischer-Krause> =item How do I sort an array by (anything)? @@ -1357,6 +1356,8 @@ array of hashes or arrays? =item How can I use a reference as a hash key? +=item How can I check if a key exists in a multilevel hash? + =back =item Data: Misc @@ -1542,7 +1543,7 @@ X<regular expression, legibility> X</x> Comments Outside the Regex, Comments Inside the Regex, Different Delimiters -=item I'm having trouble matching over more than one line. What's wrong? +=item I'm having trouble matching over more than one line. What's wrong? X<regex, multiline> X<regexp, multiline> X<regular expression, multiline> =item How can I pull out lines between two patterns that are themselves on @@ -1563,7 +1564,7 @@ Convince everyone not to use XML or HTML in the first place X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in> X<$RS, regexes in> -=item How do I substitute case insensitively on the LHS while preserving +=item How do I substitute case-insensitively on the LHS while preserving case on the RHS? X<replace, case preserving> X<substitute, case preserving> X<substitution, case preserving> X<s, case preserving> @@ -1580,7 +1581,7 @@ X<regex, escaping> X<regexp, escaping> X<regular expression, escaping> =item What is C</o> really for? X</o, regular expressions> X<compile, regular expressions> -=item How do I use a regular expression to strip C style comments from a +=item How do I use a regular expression to strip C-style comments from a file? =item Can I use Perl regular expressions to match balanced text? @@ -1588,7 +1589,7 @@ X<regex, matching balanced test> X<regexp, matching balanced test> X<regular expression, matching balanced test> X<possessive> X<PARNO> X<Text::Balanced> X<Regexp::Common> X<backtracking> X<recursion> -=item What does it mean that regexes are greedy? How can I get around it? +=item What does it mean that regexes are greedy? How can I get around it? X<greedy> X<greediness> =item How do I process each word on each line? @@ -1612,7 +1613,7 @@ X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`> =item What good is C<\G> in a regular expression? X<\G> -=item Are Perl regexes DFAs or NFAs? Are they POSIX compliant? +=item Are Perl regexes DFAs or NFAs? Are they POSIX compliant? X<DFA> X<NFA> X<POSIX> =item What's wrong with using grep in a void context? @@ -1864,7 +1865,7 @@ module: =item What is the correct form of response from a CGI script? -=item My CGI script runs from the command line but not the browser. (500 +=item My CGI script runs from the command line but not the browser. (500 Server Error) =item How can I get better error messages from a CGI program? @@ -2095,12 +2096,13 @@ X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=> X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<//=> X<.=> X<%=> X<^=> X<x=> +=item The Triple-Dot Operator +X<...> X<... operator> X<yada-yada operator> X<whatever operator> +X<triple-dot operator> + =item Comma Operator X<comma> X<operator, comma> X<,> -=item Yada Yada Operator -X<...> X<... operator> X<yada yada operator> - =item List Operators (Rightward) X<operator, list, rightward> X<list operator> @@ -2126,16 +2128,19 @@ X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m> X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>> X<escape sequence> X<escape> +[1], [2], [3], [4], [5], [6], [7], [8] + =item Regexp Quote-Like Operators X<operator, regexp> -qr/STRING/msixpo X<qr> X</i> X</m> X</o> X</s> X</x> X</p>, -m/PATTERN/msixpogc X<m> X<operator, match> X<regexp, options> X<regexp> +qr/STRING/msixpodual X<qr> X</i> X</m> X</o> X</s> X</x> X</p>, +m/PATTERN/msixpodualgc 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, The empty pattern //, Matching in list context, \G -assertion, ?PATTERN? X<?>, s/PATTERN/REPLACEMENT/msixpogce X<substitute> +/PATTERN/msixpodualgc, The empty pattern //, Matching in list context, \G +assertion, m?PATTERN?msixpodualgc X<?> X<operator, match-once>, +?PATTERN?msixpodualgc, s/PATTERN/REPLACEMENT/msixpodualgcer 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> +X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e> X</r> =item Quote-Like Operators X<operator, quote-like> @@ -2143,8 +2148,8 @@ X<operator, quote-like> q/STRING/ X<q> X<quote, single> X<'> X<''>, 'STRING', qq/STRING/ X<qq> X<quote, double> X<"> X<"">, "STRING", qx/STRING/ X<qx> X<`> X<``> X<backtick>, `STRING`, qw/STRING/ X<qw> X<quote, list> X<quote, words>, -tr/SEARCHLIST/REPLACEMENTLIST/cds X<tr> X<y> X<transliterate> X</c> X</d> -X</s>, y/SEARCHLIST/REPLACEMENTLIST/cds, <<EOF X<here-doc> X<heredoc> +tr/SEARCHLIST/REPLACEMENTLIST/cdsr X<tr> X<y> X<transliterate> X</c> X</d> +X</s>, y/SEARCHLIST/REPLACEMENTLIST/cdsr, <<EOF X<here-doc> X<heredoc> X<here-document> X<<< << >>>, Double Quotes, Single Quotes, Backticks =item Gory details of parsing quoted constructs @@ -2256,12 +2261,12 @@ expressions and pattern matching X<regular expression> X<regex> X<regexp>, Numeric functions X<numeric> X<number> X<trigonometric> X<trigonometry>, Functions for real @ARRAYs X<array>, Functions for list data X<list>, Functions for real %HASHes X<hash>, Input and output functions X<I/O> -X<input> X<output> X<dbm>, Functions for fixed length data or records, +X<input> X<output> X<dbm>, Functions for fixed-length data or records, Functions for filehandles, files, or directories X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>, Keywords related to the control -flow of your Perl program X<control flow>, Keywords related to switch, -Keywords related to scoping, Miscellaneous functions, Functions for -processes and process groups X<process> X<pid> X<process id>, Keywords +flow of your Perl program X<control flow>, Keywords related to the switch +feature, Keywords related to scoping, Miscellaneous functions, Functions +for processes and process groups X<process> X<pid> X<process id>, Keywords related to Perl modules X<module>, Keywords related to classes and object-orientation X<object> X<class> X<package>, Low-level socket functions X<socket> X<sock>, System V interprocess communication functions @@ -2297,76 +2302,80 @@ SOCKET,NAME X<connect>, continue BLOCK X<continue>, continue, cos EXPR X<cos> X<cosine> X<acos> X<arccosine>, cos, crypt PLAINTEXT,SALT X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password> X<decrypt> X<cryptography> X<passwd> X<encrypt>, dbmclose HASH X<dbmclose>, dbmopen -HASH,DBNAME,MASK X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>, defined EXPR -X<defined> X<undef> X<undefined>, defined, delete EXPR X<delete>, die LIST -X<die> X<throw> X<exception> X<raise> X<$@> X<abort>, do BLOCK X<do> -X<block>, do SUBROUTINE(LIST) X<do>, do EXPR X<do>, dump LABEL X<dump> -X<core> X<undump>, dump, each HASH X<each> X<hash, iterator>, 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 +HASH,DBNAME,MASK X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>, default BLOCK, +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>, +each ARRAY X<array, iterator>, each EXPR, 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>, given EXPR BLOCK X<given>, given BLOCK, +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, If C<use bytes> is -in effect:, On EBCDIC platforms, On ASCII platforms, Otherwise, If EXPR has -the UTF8 flag set, Otherwise, if C<use locale> is in effect, Otherwise, if -C<use feature 'unicode_strings'> is in effect:, Otherwise:, On EBCDIC -platforms, On ASCII platforms, 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 declarations> X<unimporting>, 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 +X<keys> X<key>, keys ARRAY, keys EXPR, kill SIGNAL, LIST X<kill> X<signal>, +last LABEL X<last> X<break>, last, lc EXPR X<lc> X<lowercase>, lc, If C<use +bytes> is in effect:, On EBCDIC platforms, On ASCII platforms, Otherwise, +If EXPR has the UTF8 flag set, Otherwise, if C<use locale> is in effect, +Otherwise, if C<use feature 'unicode_strings'> is in effect:, Otherwise:, +On EBCDIC platforms, On ASCII platforms, 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 declarations> +X<unimporting>, 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 VERSION X<package> X<module> X<namespace> -X<version>, package NAMESPACE, 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 +X<pack>, package NAMESPACE, package NAMESPACE VERSION X<package> X<module> +X<namespace> X<version>, package NAMESPACE BLOCK, package NAMESPACE VERSION +BLOCK X<package> X<module> X<namespace> X<version>, pipe +READHANDLE,WRITEHANDLE X<pipe>, pop ARRAY X<pop> X<stack>, pop EXPR, pop, +pos SCALAR X<pos> X<match, position>, pos, print FILEHANDLE LIST X<print>, +print FILEHANDLE, print LIST, print, printf FILEHANDLE FORMAT, LIST +X<printf>, printf FILEHANDLE, printf FORMAT, LIST, printf, prototype +FUNCTION X<prototype>, push ARRAY,LIST X<push> X<stack>, push EXPR,LIST, +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 @@ -2376,36 +2385,37 @@ X<require>, require EXPR, require, reset EXPR X<reset>, reset, return EXPR X<return>, return, reverse LIST X<reverse> X<rev> X<invert>, rewinddir DIRHANDLE X<rewinddir>, rindex STR,SUBSTR,POSITION X<rindex>, rindex STR,SUBSTR, rmdir FILENAME X<rmdir> X<rd> X<directory, remove>, rmdir, -s///, say FILEHANDLE LIST X<say>, say LIST, say, scalar EXPR X<scalar> -X<context>, seek FILEHANDLE,POSITION,WHENCE X<seek> X<fseek> X<filehandle, -position>, seekdir DIRHANDLE,POS X<seekdir>, select FILEHANDLE X<select> -X<filehandle, default>, select, select RBITS,WBITS,EBITS,TIMEOUT X<select>, -semctl ID,SEMNUM,CMD,ARG X<semctl>, semget KEY,NSEMS,FLAGS X<semget>, semop -KEY,OPSTRING X<semop>, send SOCKET,MSG,FLAGS,TO X<send>, send -SOCKET,MSG,FLAGS, setpgrp PID,PGRP X<setpgrp> X<group>, setpriority -WHICH,WHO,PRIORITY X<setpriority> X<priority> X<nice> X<renice>, setsockopt -SOCKET,LEVEL,OPTNAME,OPTVAL X<setsockopt>, shift ARRAY X<shift>, shift, -shmctl ID,CMD,ARG X<shmctl>, shmget KEY,SIZE,FLAGS X<shmget>, shmread -ID,VAR,POS,SIZE X<shmread> X<shmwrite>, shmwrite ID,STRING,POS,SIZE, -shutdown SOCKET,HOW X<shutdown>, sin EXPR X<sin> X<sine> X<asin> -X<arcsine>, sin, sleep EXPR X<sleep> X<pause>, sleep, socket -SOCKET,DOMAIN,TYPE,PROTOCOL X<socket>, socketpair -SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL X<socketpair>, sort SUBNAME LIST -X<sort> X<qsort> X<quicksort> X<mergesort>, sort BLOCK LIST, sort LIST, -splice ARRAY,OFFSET,LENGTH,LIST X<splice>, splice ARRAY,OFFSET,LENGTH, -splice ARRAY,OFFSET, splice ARRAY, split /PATTERN/,EXPR,LIMIT X<split>, -split /PATTERN/,EXPR, split /PATTERN/, split, sprintf FORMAT, LIST -X<sprintf>, format parameter index, flags, vector flag, (minimum) width, -precision, or maximum width X<precision>, size, order of arguments, sqrt -EXPR X<sqrt> X<root> X<square root>, sqrt, srand EXPR X<srand> X<seed> -X<randseed>, srand, stat FILEHANDLE X<stat> X<file, status> X<ctime>, stat -EXPR, stat DIRHANDLE, stat, state EXPR X<state>, state TYPE EXPR, state -EXPR : ATTRS, state TYPE EXPR : ATTRS, study SCALAR X<study>, study, sub -NAME BLOCK X<sub>, sub NAME (PROTO) BLOCK, sub NAME : ATTRS BLOCK, sub NAME -(PROTO) : ATTRS BLOCK, substr EXPR,OFFSET,LENGTH,REPLACEMENT X<substr> -X<substring> X<mid> X<left> X<right>, substr EXPR,OFFSET,LENGTH, substr -EXPR,OFFSET, symlink OLDFILE,NEWFILE X<symlink> X<link> X<symbolic link> -X<link, symbolic>, syscall NUMBER, LIST X<syscall> X<system call>, sysopen +s///, say FILEHANDLE LIST X<say>, say FILEHANDLE, say LIST, say, scalar +EXPR X<scalar> X<context>, seek FILEHANDLE,POSITION,WHENCE X<seek> X<fseek> +X<filehandle, position>, seekdir DIRHANDLE,POS X<seekdir>, select +FILEHANDLE X<select> X<filehandle, default>, select, select +RBITS,WBITS,EBITS,TIMEOUT X<select>, semctl ID,SEMNUM,CMD,ARG X<semctl>, +semget KEY,NSEMS,FLAGS X<semget>, semop KEY,OPSTRING X<semop>, send +SOCKET,MSG,FLAGS,TO X<send>, send SOCKET,MSG,FLAGS, setpgrp PID,PGRP +X<setpgrp> X<group>, setpriority WHICH,WHO,PRIORITY X<setpriority> +X<priority> X<nice> X<renice>, setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL +X<setsockopt>, shift ARRAY X<shift>, shift EXPR, shift, shmctl ID,CMD,ARG +X<shmctl>, shmget KEY,SIZE,FLAGS X<shmget>, shmread ID,VAR,POS,SIZE +X<shmread> X<shmwrite>, shmwrite ID,STRING,POS,SIZE, shutdown SOCKET,HOW +X<shutdown>, sin EXPR X<sin> X<sine> X<asin> X<arcsine>, sin, sleep EXPR +X<sleep> X<pause>, sleep, socket SOCKET,DOMAIN,TYPE,PROTOCOL X<socket>, +socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL X<socketpair>, sort SUBNAME +LIST X<sort> X<qsort> X<quicksort> X<mergesort>, sort BLOCK LIST, sort +LIST, splice ARRAY or EXPR,OFFSET,LENGTH,LIST X<splice>, splice ARRAY or +EXPR,OFFSET,LENGTH, splice ARRAY or EXPR,OFFSET, splice ARRAY or EXPR, +split /PATTERN/,EXPR,LIMIT X<split>, split /PATTERN/,EXPR, split /PATTERN/, +split, sprintf FORMAT, LIST X<sprintf>, format parameter index, flags, +vector flag, (minimum) width, precision, or maximum width X<precision>, +size, order of arguments, sqrt EXPR X<sqrt> X<root> X<square root>, sqrt, +srand EXPR X<srand> X<seed> X<randseed>, srand, stat FILEHANDLE X<stat> +X<file, status> X<ctime>, stat EXPR, stat DIRHANDLE, stat, state EXPR +X<state>, state TYPE EXPR, state EXPR : ATTRS, state TYPE EXPR : ATTRS, +study SCALAR X<study>, study, sub NAME BLOCK X<sub>, sub NAME (PROTO) +BLOCK, sub NAME : ATTRS BLOCK, sub NAME (PROTO) : ATTRS BLOCK, substr +EXPR,OFFSET,LENGTH,REPLACEMENT X<substr> X<substring> X<mid> X<left> +X<right>, substr EXPR,OFFSET,LENGTH, substr EXPR,OFFSET, symlink +OLDFILE,NEWFILE X<symlink> X<link> X<symbolic link> X<link, symbolic>, +syscall NUMBER, LIST X<syscall> X<system call>, sysopen FILEHANDLE,FILENAME,MODE X<sysopen>, sysopen FILEHANDLE,FILENAME,MODE,PERMS, sysread FILEHANDLE,SCALAR,LENGTH,OFFSET X<sysread>, sysread FILEHANDLE,SCALAR,LENGTH, sysseek @@ -2419,12 +2429,13 @@ truncate EXPR,LENGTH, uc EXPR X<uc> X<uppercase> X<toupper>, uc, ucfirst EXPR X<ucfirst> X<uppercase>, ucfirst, umask EXPR X<umask>, umask, undef EXPR X<undef> X<undefine>, undef, unlink LIST X<unlink> X<delete> X<remove> X<rm> X<del>, unlink, unpack TEMPLATE,EXPR X<unpack>, unpack TEMPLATE, -untie VARIABLE X<untie>, unshift ARRAY,LIST X<unshift>, use Module VERSION -LIST X<use> X<module> X<import>, use Module VERSION, use Module LIST, use -Module, use VERSION, utime LIST X<utime>, values HASH X<values>, 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, +untie VARIABLE X<untie>, unshift ARRAY,LIST X<unshift>, unshift EXPR,LIST, +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>, values ARRAY, values EXPR, 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>, when EXPR +BLOCK X<when>, when BLOCK, write FILEHANDLE X<write>, write EXPR, write, y/// =back @@ -2690,6 +2701,24 @@ First:, Second:, Third:, Fourth:, Fifth:, Sixth: =back +=head2 perlpodstyle - Perl POD style guide + +=over 4 + +=item DESCRIPTION + +NAME, SYNOPSIS, DESCRIPTION, OPTIONS, RETURN VALUE, ERRORS, DIAGNOSTICS, +EXAMPLES, ENVIRONMENT, FILES, CAVEATS, BUGS, RESTRICTIONS, NOTES, AUTHOR, +HISTORY, COPYRIGHT AND LICENSE, SEE ALSO + +=item SEE ALSO + +=item AUTHOR + +=item COPYRIGHT AND LICENSE + +=back + =head2 perlrun - how to execute the Perl interpreter =over 4 @@ -2713,7 +2742,7 @@ X<perl, command switches> X<command switches> B<-0>[I<octal/hexadecimal>] X<-0> X<$/>, B<-a> X<-a> X<autosplit>, B<-C [I<number/list>]> X<-C>, B<-c> X<-c>, B<-d> X<-d> X<-dt>, B<-dt>, -B<-d:>I<foo[=bar,baz]> X<-d> X<-dt>, B<-dt:>I<foo[=bar,baz]>, +B<-d:>I<MOD[=bar,baz]> X<-d> X<-dt>, B<-dt:>I<MOD[=bar,baz]>, B<-D>I<letters> X<-D> X<DEBUGGING> X<-DDEBUGGING>, B<-D>I<number>, B<-e> I<commandline> X<-e>, B<-E> I<commandline> X<-E>, B<-f> X<-f> X<sitecustomize> X<sitecustomize.pl>, B<-F>I<pattern> X<-F>, B<-h> X<-h>, @@ -2802,7 +2831,7 @@ X<warning, reporting> X<warning, registering> =over 4 -=item Calling the debugger +=item Calling the Debugger perl -d program_name, perl -d -e 0, perl -d:Ptkdb program_name, perl -dt threaded_program_name @@ -2867,16 +2896,16 @@ X<debugger option, UsageOnly>, C<TTY> X<debugger option, TTY>, C<noTTY> X<debugger option, noTTY>, C<ReadLine> X<debugger option, ReadLine>, C<NonStop> X<debugger option, NonStop> -=item Debugger input/output +=item Debugger Input/Output Prompt, Multiline commands, Stack backtrace X<backtrace> X<stack, backtrace>, Line Listing Format, Frame listing -=item Debugging compile-time statements +=item Debugging Compile-Time Statements =item Debugger Customization -=item Readline Support / History in the debugger +=item Readline Support / History in the Debugger =item Editor Support for Debugging @@ -2885,11 +2914,11 @@ X<profile> X<profiling> X<profiler> =back -=item Debugging regular expressions +=item Debugging Regular Expressions X<regular expression, debugging> X<regex, debugging> X<regexp, debugging> -=item Debugging memory usage +=item Debugging Memory Usage X<memory usage> =item SEE ALSO @@ -2906,78 +2935,98 @@ X<memory usage> =over 4 -=item Predefined Names +=item The Syntax of Variable Names -$ARG, $_ X<$_> X<$ARG>, $a, $b X<$a> X<$b>, $<I<digits>> ($1, $2, ...) -X<$1> X<$2> X<$3>, $MATCH, $& X<$&> X<$MATCH>, ${^MATCH} X<${^MATCH}>, -$PREMATCH, $` X<$`> X<$PREMATCH>, ${^PREMATCH} X<${^PREMATCH}>, $POSTMATCH, -$' X<$'> X<$POSTMATCH>, ${^POSTMATCH} X<${^POSTMATCH}>, $LAST_PAREN_MATCH, -$+ X<$+> X<$LAST_PAREN_MATCH>, $LAST_SUBMATCH_RESULT, $^N X<$^N>, -@LAST_MATCH_END, @+ X<@+> X<@LAST_MATCH_END>, %LAST_PAREN_MATCH, %+ X<%+>, -HANDLE->input_line_number(EXPR), $INPUT_LINE_NUMBER, $NR, $. X<$.> X<$NR> -X<$INPUT_LINE_NUMBER> X<line number>, -IO::Handle->input_record_separator(EXPR), $INPUT_RECORD_SEPARATOR, $RS, $/ -X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>, HANDLE->autoflush(EXPR), -$OUTPUT_AUTOFLUSH, $| X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>, -IO::Handle->output_field_separator EXPR, $OUTPUT_FIELD_SEPARATOR, $OFS, $, -X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>, -IO::Handle->output_record_separator EXPR, $OUTPUT_RECORD_SEPARATOR, $ORS, -$\ X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>, $LIST_SEPARATOR, $" X<$"> -X<$LIST_SEPARATOR>, $SUBSCRIPT_SEPARATOR, $SUBSEP, $; X<$;> X<$SUBSEP> -X<SUBSCRIPT_SEPARATOR>, HANDLE->format_page_number(EXPR), -$FORMAT_PAGE_NUMBER, $% X<$%> X<$FORMAT_PAGE_NUMBER>, -HANDLE->format_lines_per_page(EXPR), $FORMAT_LINES_PER_PAGE, $= X<$=> -X<$FORMAT_LINES_PER_PAGE>, HANDLE->format_lines_left(EXPR), -$FORMAT_LINES_LEFT, $- X<$-> X<$FORMAT_LINES_LEFT>, @LAST_MATCH_START, @- -X<@-> X<@LAST_MATCH_START>, C<$`> is the same as C<substr($var, 0, $-[0])>, -C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>, C<$'> is the -same as C<substr($var, $+[0])>, C<$1> is the same as C<substr($var, $-[1], -$+[1] - $-[1])>, C<$2> is the same as C<substr($var, $-[2], $+[2] - -$-[2])>, C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>, %- -X<%->, HANDLE->format_name(EXPR), $FORMAT_NAME, $~ X<$~> X<$FORMAT_NAME>, -HANDLE->format_top_name(EXPR), $FORMAT_TOP_NAME, $^ X<$^> -X<$FORMAT_TOP_NAME>, IO::Handle->format_line_break_characters EXPR, -$FORMAT_LINE_BREAK_CHARACTERS, $: X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>, -IO::Handle->format_formfeed EXPR, $FORMAT_FORMFEED, $^L X<$^L> -X<$FORMAT_FORMFEED>, $ACCUMULATOR, $^A X<$^A> X<$ACCUMULATOR>, -$CHILD_ERROR, $? X<$?> X<$CHILD_ERROR>, ${^CHILD_ERROR_NATIVE} -X<$^CHILD_ERROR_NATIVE>, ${^ENCODING} X<$^ENCODING>, $OS_ERROR, $ERRNO, $! -X<$!> X<$ERRNO> X<$OS_ERROR>, %OS_ERROR, %ERRNO, %! X<%!>, -$EXTENDED_OS_ERROR, $^E X<$^E> X<$EXTENDED_OS_ERROR>, $EVAL_ERROR, $@ X<$@> -X<$EVAL_ERROR>, $PROCESS_ID, $PID, $$ X<$$> X<$PID> X<$PROCESS_ID>, -$REAL_USER_ID, $UID, $< X<< $< >> X<$UID> X<$REAL_USER_ID>, -$EFFECTIVE_USER_ID, $EUID, $> X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>, +=back + +=item SPECIAL VARIABLES + +=over 4 + +=item General Variables + +$ARG, $_ X<$_> X<$ARG>, @ARG, @_ X<@_> X<@ARG>, $LIST_SEPARATOR, $" X<$"> +X<$LIST_SEPARATOR>, $PROCESS_ID, $PID, $$ X<$$> X<$PID> X<$PROCESS_ID>, $REAL_GROUP_ID, $GID, $( X<$(> X<$GID> X<$REAL_GROUP_ID>, $EFFECTIVE_GROUP_ID, $EGID, $) X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>, -$PROGRAM_NAME, $0 X<$0> X<$PROGRAM_NAME>, $[ X<$[>, $] X<$]>, $COMPILING, -$^C X<$^C> X<$COMPILING>, $DEBUGGING, $^D X<$^D> X<$DEBUGGING>, -${^RE_DEBUG_FLAGS}, ${^RE_TRIE_MAXBUF}, $SYSTEM_FD_MAX, $^F X<$^F> -X<$SYSTEM_FD_MAX>, $^H, %^H, $INPLACE_EDIT, $^I X<$^I> X<$INPLACE_EDIT>, -$^M X<$^M>, $OSNAME, $^O X<$^O> X<$OSNAME>, ${^OPEN}, $PERLDB, $^P X<$^P> -X<$PERLDB>, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x100, 0x200, -0x400, $LAST_REGEXP_CODE_RESULT, $^R X<$^R> X<$LAST_REGEXP_CODE_RESULT>, -$EXCEPTIONS_BEING_CAUGHT, $^S X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>, -$BASETIME, $^T X<$^T> X<$BASETIME>, ${^TAINT}, ${^UNICODE}, ${^UTF8CACHE}, -${^UTF8LOCALE}, $PERL_VERSION, $^V X<$^V> X<$PERL_VERSION>, $WARNING, $^W -X<$^W> X<$WARNING>, ${^WARNING_BITS}, ${^WIN32_SLOPPY_STAT} +$PROGRAM_NAME, $0 X<$0> X<$PROGRAM_NAME>, $SUBSCRIPT_SEPARATOR, $SUBSEP, $; +X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>, $REAL_USER_ID, $UID, $< X<< $< >> +X<$UID> X<$REAL_USER_ID>, $EFFECTIVE_USER_ID, $EUID, $> X<< $> >> X<$EUID> +X<$EFFECTIVE_USER_ID>, $a, $b X<$a> X<$b>, $COMPILING, $^C X<$^C> +X<$COMPILING>, $DEBUGGING, $^D X<$^D> X<$DEBUGGING>, ${^ENCODING} +X<${^ENCODING}>, %ENV X<%ENV>, $SYSTEM_FD_MAX, $^F X<$^F> +X<$SYSTEM_FD_MAX>, @F X<@F>, ${^GLOBAL_PHASE} X<${^GLOBAL_PHASE}>, +CONSTRUCT, START, CHECK, INIT, RUN, END, DESTRUCT, $^H X<$^H>, %^H X<%^H>, +@INC X<@INC>, %INC X<%INC>, $INPLACE_EDIT, $^I X<$^I> X<$INPLACE_EDIT>, $^M +X<$^M>, $OSNAME, $^O X<$^O> X<$OSNAME>, ${^OPEN} X<${^OPEN}>, $PERLDB, $^P +X<$^P> X<$PERLDB>, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x100, +0x200, 0x400, %SIG X<%SIG>, $BASETIME, $^T X<$^T> X<$BASETIME>, ${^TAINT} +X<${^TAINT}>, ${^UNICODE} X<${^UNICODE}>, ${^UTF8CACHE} X<${^UTF8CACHE}>, +${^UTF8LOCALE} X<${^UTF8LOCALE}>, $PERL_VERSION, $^V X<$^V> +X<$PERL_VERSION>, ${^WIN32_SLOPPY_STAT} X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>, $EXECUTABLE_NAME, $^X X<$^X> -X<$EXECUTABLE_NAME>, ARGV X<ARGV>, $ARGV X<$ARGV>, @ARGV X<@ARGV>, ARGVOUT -X<ARGVOUT>, @F X<@F>, @INC X<@INC>, @ARG, @_ X<@_> X<@ARG>, %INC X<%INC>, -%ENV, $ENV{expr} X<%ENV>, %SIG, $SIG{expr} X<%SIG> +X<$EXECUTABLE_NAME> + +=item Variables related to regular expressions + +$<I<digits>> ($1, $2, ...) X<$1> X<$2> X<$3>, $MATCH, $& X<$&> X<$MATCH>, +${^MATCH} X<${^MATCH}>, $PREMATCH, $` X<$`> X<$PREMATCH> X<${^PREMATCH}>, +${^PREMATCH} X<$`> X<${^PREMATCH}>, $POSTMATCH, $' X<$'> X<$POSTMATCH> +X<${^POSTMATCH}> X<@->, ${^POSTMATCH} X<${^POSTMATCH}> X<$'> X<$POSTMATCH>, +$LAST_PAREN_MATCH, $+ X<$+> X<$LAST_PAREN_MATCH>, $LAST_SUBMATCH_RESULT, +$^N X<$^N> X<$LAST_SUBMATCH_RESULT>, @LAST_MATCH_END, @+ X<@+> +X<@LAST_MATCH_END>, %LAST_PAREN_MATCH, %+ X<%+> X<%LAST_PAREN_MATCH>, +@LAST_MATCH_START, @- X<@-> X<@LAST_MATCH_START>, C<$`> is the same as +C<substr($var, 0, $-[0])>, C<$&> is the same as C<substr($var, $-[0], $+[0] +- $-[0])>, C<$'> is the same as C<substr($var, $+[0])>, C<$1> is the same +as C<substr($var, $-[1], $+[1] - $-[1])>, C<$2> is the same as +C<substr($var, $-[2], $+[2] - $-[2])>, C<$3> is the same as C<substr($var, +$-[3], $+[3] - $-[3])>, %LAST_MATCH_START, %- X<%-> X<%LAST_MATCH_START>, +$LAST_REGEXP_CODE_RESULT, $^R X<$^R> X<$LAST_REGEXP_CODE_RESULT>, +${^RE_DEBUG_FLAGS} X<${^RE_DEBUG_FLAGS}>, ${^RE_TRIE_MAXBUF} +X<${^RE_TRIE_MAXBUF}> + +=item Variables related to filehandles + +$ARGV X<$ARGV>, @ARGV X<@ARGV>, ARGV X<ARGV>, ARGVOUT X<ARGVOUT>, +Handle->output_field_separator( EXPR ), $OUTPUT_FIELD_SEPARATOR, $OFS, $, +X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>, HANDLE->input_line_number( EXPR +), $INPUT_LINE_NUMBER, $NR, $. X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line +number>, HANDLE->input_record_separator( EXPR ), $INPUT_RECORD_SEPARATOR, +$RS, $/ X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>, +Handle->output_record_separator( EXPR ), $OUTPUT_RECORD_SEPARATOR, $ORS, $\ +X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>, HANDLE->autoflush( EXPR ), +$OUTPUT_AUTOFLUSH, $| X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>, +$ACCUMULATOR, $^A X<$^A> X<$ACCUMULATOR>, HANDLE->format_formfeed(EXPR), +$FORMAT_FORMFEED, $^L X<$^L> X<$FORMAT_FORMFEED>, +HANDLE->format_page_number(EXPR), $FORMAT_PAGE_NUMBER, $% X<$%> +X<$FORMAT_PAGE_NUMBER>, HANDLE->format_lines_left(EXPR), +$FORMAT_LINES_LEFT, $- X<$-> X<$FORMAT_LINES_LEFT>, +Handle->format_line_break_characters EXPR, $FORMAT_LINE_BREAK_CHARACTERS, +$: X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>, +HANDLE->format_lines_per_page(EXPR), $FORMAT_LINES_PER_PAGE, $= X<$=> +X<$FORMAT_LINES_PER_PAGE>, HANDLE->format_top_name(EXPR), $FORMAT_TOP_NAME, +$^ X<$^> X<$FORMAT_TOP_NAME>, HANDLE->format_name(EXPR), $FORMAT_NAME, $~ +X<$~> X<$FORMAT_NAME> -=item Names that are no longer special +=item Error Variables +X<error> X<exception> -$# X<$#>, $* X<$*> +${^CHILD_ERROR_NATIVE} X<$^CHILD_ERROR_NATIVE>, $EXTENDED_OS_ERROR, $^E +X<$^E> X<$EXTENDED_OS_ERROR>, $EXCEPTIONS_BEING_CAUGHT, $^S X<$^S> +X<$EXCEPTIONS_BEING_CAUGHT>, $WARNING, $^W X<$^W> X<$WARNING>, +${^WARNING_BITS} X<${^WARNING_BITS}>, $OS_ERROR, $ERRNO, $! X<$!> X<$ERRNO> +X<$OS_ERROR>, %OS_ERROR, %ERRNO, %! X<%!> X<%OS_ERROR> X<%ERRNO>, +$CHILD_ERROR, $? X<$?> X<$CHILD_ERROR>, $EVAL_ERROR, $@ X<$@> +X<$EVAL_ERROR> -=item Error Indicators -X<error> X<exception> +=item Deprecated and removed variables -=item Technical Note on the Syntax of Variable Names +$OFMT, $# X<$#> X<$OFMT>, $* X<$*>, $ARRAY_BASE, $[ X<$[> X<$ARRAY_BASE>, +$OLD_PERL_VERSION, $] X<$]> X<$OLD_PERL_VERSION> =back -=item BUGS - =back =head2 perlre - Perl regular expressions @@ -2994,7 +3043,8 @@ m X</m> X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>, s X</s> X<regex, single-line> X<regexp, single-line> X<regular expression, single-line>, i X</i> X<regex, case-insensitive> X<regexp, case-insensitive> X<regular expression, case-insensitive>, x X</x>, p X</p> -X<regex, preserve> X<regexp, preserve>, g and c X</g> X</c> +X<regex, preserve> X<regexp, preserve>, g and c X</g> X</c>, a, d, l and u +X</a> X</d> X</l> X</u> =item Regular Expressions @@ -3004,26 +3054,28 @@ X<regex, preserve> X<regexp, preserve>, g and c X</g> X</c> =item Extended Patterns -C<(?#text)> X<(?#)>, C<(?pimsx-imsx)> X<(?)>, C<(?:pattern)> X<(?:)>, -C<(?imsx-imsx:pattern)>, C<(?|pattern)> X<(?|)> X<Branch reset>, -Look-Around Assertions X<look-around assertion> X<lookaround assertion> -X<look-around> X<lookaround>, C<(?=pattern)> X<(?=)> X<look-ahead, -positive> X<lookahead, positive>, C<(?!pattern)> X<(?!)> X<look-ahead, -negative> X<lookahead, negative>, C<(?<=pattern)> C<\K> X<(?<=)> -X<look-behind, positive> X<lookbehind, positive> X<\K>, C<(?<!pattern)> -X<(?<!)> X<look-behind, negative> X<lookbehind, negative>, -C<(?'NAME'pattern)>, C<< (?<NAME>pattern) >> X<< (?<NAME>) >> X<(?'NAME')> -X<named capture> X<capture>, C<< \k<NAME> >>, C<< \k'NAME' >>, C<(?{ code -})> X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, -code in>, C<(??{ code })> X<(??{})> X<regex, postponed> X<regexp, -postponed> X<regular expression, postponed>, C<(?PARNO)> C<(?-PARNO)> -C<(?+PARNO)> C<(?R)> C<(?0)> X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> -X<(?+1)> X<(?-PARNO)> X<(?+PARNO)> X<regex, recursive> X<regexp, recursive> -X<regular expression, recursive> X<regex, relative recursion>, C<(?&NAME)> -X<(?&NAME)>, C<(?(condition)yes-pattern|no-pattern)> X<(?()>, -C<(?(condition)yes-pattern)>, (1) (2) .., (<NAME>) ('NAME'), (?{ CODE }), -(R), (R1) (R2) .., (R&NAME), (DEFINE), C<< (?>pattern) >> X<backtrack> -X<backtracking> X<atomic> X<possessive> +C<(?#text)> X<(?#)>, C<(?adlupimsx-imsx)>, C<(?^alupimsx)> X<(?)> X<(?^)>, +C<(?:pattern)> X<(?:)>, C<(?adluimsx-imsx:pattern)>, C<(?^aluimsx:pattern)> +X<(?^:)>, C<(?|pattern)> X<(?|)> X<Branch reset>, Look-Around Assertions +X<look-around assertion> X<lookaround assertion> X<look-around> +X<lookaround>, C<(?=pattern)> X<(?=)> X<look-ahead, positive> X<lookahead, +positive>, C<(?!pattern)> X<(?!)> X<look-ahead, negative> X<lookahead, +negative>, C<(?<=pattern)> C<\K> X<(?<=)> X<look-behind, positive> +X<lookbehind, positive> X<\K>, C<(?<!pattern)> X<(?<!)> X<look-behind, +negative> X<lookbehind, negative>, C<(?'NAME'pattern)>, C<< +(?<NAME>pattern) >> X<< (?<NAME>) >> X<(?'NAME')> X<named capture> +X<capture>, C<< \k<NAME> >>, C<< \k'NAME' >>, C<(?{ code })> X<(?{})> +X<regex, code in> X<regexp, code in> X<regular expression, code in>, C<(??{ +code })> X<(??{})> X<regex, postponed> X<regexp, postponed> X<regular +expression, postponed>, C<(?PARNO)> C<(?-PARNO)> C<(?+PARNO)> C<(?R)> +C<(?0)> X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> X<(?+1)> X<(?-PARNO)> +X<(?+PARNO)> X<regex, recursive> X<regexp, recursive> X<regular expression, +recursive> X<regex, relative recursion>, C<(?&NAME)> X<(?&NAME)>, +C<(?(condition)yes-pattern|no-pattern)> X<(?()>, +C<(?(condition)yes-pattern)>, (1) (2) .., (<NAME>) ('NAME'), (?=...) +(?!...) (?<=...) (?<!...), (?{ CODE }), (R), (R1) (R2) .., (R&NAME), +(DEFINE), C<< (?>pattern) >> X<backtrack> X<backtracking> X<atomic> +X<possessive> =item Special Backtracking Control Verbs @@ -3052,12 +3104,12 @@ C<(?(condition)yes-pattern|no-pattern)> =item Creating Custom RE Engines -=back - =item PCRE/Python Support C<< (?PE<lt>NAMEE<gt>pattern) >>, C<< (?P=NAME) >>, C<< (?P>NAME) >> +=back + =item BUGS =item SEE ALSO @@ -3112,17 +3164,24 @@ Escapes =item The dot =item Backslash sequences -X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\p> X<\P> +X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\p> X<\P> X<\N> X<\v> X<\V> X<\h> X<\H> X<word> X<whitespace> +If the C</a> modifier is in effect .., otherwise .., For code points above +255 .., For code points below 256 .., if locale rules are in effect .., if +Unicode rules are in effect or if on an EBCDIC platform .., otherwise .., +If the C</a> modifier is in effect .., otherwise .., For code points above +255 .., For code points below 256 .., if locale rules are in effect .., if +Unicode rules are in effect or if on an EBCDIC platform .., otherwise .., [1] =item Bracketed Character Classes -[1], [2], [3], [4], [5] (punct), [6] - -=item Locale, EBCDIC, Unicode and UTF-8 +If the C</a> modifier, is in effect .., otherwise .., For code points above +255 .., For code points below 256 .., if locale rules are in effect .., if +Unicode rules are in effect or if on an EBCDIC platform .., otherwise .., +[1], [2], [3], [4], [5], [6] =back @@ -3226,10 +3285,10 @@ X<format, text field> =item Numeric Fields X<#> X<format, numeric field> -=item The Field @* for Variable Width Multi-Line Text +=item The Field @* for Variable-Width Multi-Line Text X<@*> -=item The Field ^* for Variable Width One-line-at-a-time Text +=item The Field ^* for Variable-Width One-line-at-a-time Text X<^*> =item Specifying Values @@ -3413,12 +3472,6 @@ safe subprocesses, sockets, and semaphores) =item Handling the SIGHUP Signal in Daemons -=back - -=item Named Pipes - -=over 4 - =item Deferred Signals (Safe Signals) Long-running opcodes, Interrupting IO, Restartable system calls, Signals as @@ -3426,6 +3479,8 @@ Long-running opcodes, Interrupting IO, Restartable system calls, Signals as =back +=item Named Pipes + =item Using open() for IPC =over 4 @@ -3512,13 +3567,13 @@ files, directories and network sockets =item Lifetime of the parent process and pseudo-processes -=item CAVEATS AND LIMITATIONS +=back -BEGIN blocks, Open filehandles, Forking pipe open() not yet implemented, -Global state maintained by XSUBs, Interpreter embedded in larger -application, Thread-safety of extensions +=item CAVEATS AND LIMITATIONS -=back +BEGIN blocks, Open filehandles, Open directory handles, Forking pipe open() +not yet implemented, Global state maintained by XSUBs, Interpreter embedded +in larger application, Thread-safety of extensions =item BUGS @@ -3756,10 +3811,11 @@ gethostbyname, gethostent, getnetent, getprotoent, getservent, sethostent, setnetent, setprotoent, setservent, endpwent, endgrent, endhostent, endnetent, endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob, gmtime, ioctl FILEHANDLE,FUNCTION,SCALAR, kill, link, localtime, lstat, -msgctl, msgget, msgsnd, msgrcv, open, readlink, rename, select, semctl, -semget, semop, setgrent, setpgrp, setpriority, setpwent, setsockopt, -shmctl, shmget, shmread, shmwrite, sockatmark, socketpair, stat, symlink, -syscall, sysopen, system, times, truncate, umask, utime, wait, waitpid +msgctl, msgget, msgsnd, msgrcv, open, readlink, rename, rewinddir, select, +semctl, semget, semop, setgrent, setpgrp, setpriority, setpwent, +setsockopt, shmctl, shmget, shmread, shmwrite, sockatmark, socketpair, +stat, symlink, syscall, sysopen, system, times, truncate, umask, utime, +wait, waitpid =back @@ -3768,11 +3824,12 @@ syscall, sysopen, system, times, truncate, umask, utime, wait, waitpid Linux (x86, ARM, IA64), HP-UX, AIX, Win32, Windows 2000, Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, Windows 7, Cygwin, Solaris (x86, SPARC), OpenVMS, Alpha (7.2 and later), I64 (8.2 and later), -Symbian, NetBSD, FreeBSD, Haiku, Irix (6.5. What else?), OpenBSD, Dragonfly -BSD, MirOS BSD, time_t issues that may or may not be fixed, Symbian (Series -60 v3, 3.2 and 5 - what else?), Stratus VOS / OpenVOS, AIX +Symbian, NetBSD, FreeBSD, Debian GNU/kFreeBSD, Haiku, Irix (6.5. What +else?), OpenBSD, Dragonfly BSD, QNX Neutrino RTOS (6.5.0), MirOS BSD, +time_t issues that may or may not be fixed, Symbian (Series 60 v3, 3.2 and +5 - what else?), Stratus VOS / OpenVOS, AIX -=item EOL Platforms (Perl 5.12) +=item EOL Platforms (Perl 5.14) Atari MiNT, Apollo Domain/OS, Apple Mac OS 8/9, Tenon Machten, Windows 95, Windows 98, Windows ME, Windows NT4 @@ -3947,9 +4004,10 @@ LC_NUMERIC, LC_TIME, LANG =item Important Caveats -Input and Output Layers, Regular Expressions, C<use utf8> still needed to -enable UTF-8/UTF-EBCDIC in scripts, BOM-marked scripts and UTF-16 scripts -autodetected, C<use encoding> needed to upgrade non-Latin-1 byte strings +Safest if you "use feature 'unicode_strings'", Input and Output Layers, +C<use utf8> still needed to enable UTF-8/UTF-EBCDIC in scripts, BOM-marked +scripts and UTF-16 scripts autodetected, C<use encoding> needed to upgrade +non-Latin-1 byte strings =item Byte and Character Semantics @@ -3957,19 +4015,17 @@ autodetected, C<use encoding> needed to upgrade non-Latin-1 byte strings =item Unicode Character Properties -B<C<\p{All}>>, B<C<\p{Alnum}>>, B<C<\p{Any}>>, B<C<\p{Assigned}>>, -B<C<\p{Blank}>>, B<C<\p{Decomposition_Type: Non_Canonical}>> (Short: -C<\p{Dt=NonCanon}>), B<C<\p{Graph}>>, B<C<\p{HorizSpace}>>, B<C<\p{In=*}>>, -B<C<\p{PerlSpace}>>, B<C<\p{PerlWord}>>, B<C<\p{PosixAlnum}>>, -B<C<\p{PosixAlpha}>>, B<C<\p{PosixBlank}>>, B<C<\p{PosixCntrl}>>, -B<C<\p{PosixDigit}>>, B<C<\p{PosixGraph}>>, B<C<\p{PosixLower}>>, -B<C<\p{PosixPrint}>>, B<C<\p{PosixPunct}>>, B<C<\p{PosixSpace}>>, -B<C<\p{PosixUpper}>>, B<C<\p{Present_In: *}>> (Short: C<\p{In=*}>), -B<C<\p{Print}>>, B<C<\p{SpacePerl}>>, B<C<\p{VertSpace}>>, B<C<\p{Word}>> +B<C<\p{All}>>, B<C<\p{Alnum}>>, B<C<\p{Any}>>, B<C<\p{ASCII}>>, +B<C<\p{Assigned}>>, B<C<\p{Blank}>>, B<C<\p{Decomposition_Type: +Non_Canonical}>> (Short: C<\p{Dt=NonCanon}>), B<C<\p{Graph}>>, +B<C<\p{HorizSpace}>>, B<C<\p{In=*}>>, B<C<\p{PerlSpace}>>, +B<C<\p{PerlWord}>>, B<C<\p{Posix...}>>, B<C<\p{Present_In: *}>> (Short: +C<\p{In=*}>), B<C<\p{Print}>>, B<C<\p{SpacePerl}>>, B<C<\p{VertSpace}>>, +B<C<\p{Word}>>, B<C<\p{XPosix...}>> =item User-Defined Character Properties -=item User-Defined Case Mappings +=item User-Defined Case Mappings (for serious hackers only) =item Character Encodings for Input and Output @@ -3977,6 +4033,10 @@ B<C<\p{Print}>>, B<C<\p{SpacePerl}>>, B<C<\p{VertSpace}>>, B<C<\p{Word}>> =item Unicode Encodings +=item Non-character code points + +=item Beyond Unicode code points + =item Security Implications of Unicode =item Unicode in Perl on EBCDIC @@ -4004,8 +4064,6 @@ hackers only) =item Problems with characters in the Latin-1 Supplement range -=item Problems with case-insensitive regular expression matching - =item Interaction with Extensions =item Speed @@ -4089,7 +4147,7 @@ range? =back -=head2 perluniprops - Index of Unicode Version 5.2.0 properties in Perl +=head2 perluniprops - Index of Unicode Version 6.0.0 properties in Perl =over 4 @@ -4119,6 +4177,10 @@ form is discouraged =item Unicode regular expression properties that are NOT accepted by Perl +I<Expands_On_NFC> (XO_NFC), I<Expands_On_NFD> (XO_NFD), I<Expands_On_NFKC> +(XO_NFKC), I<Expands_On_NFKD> (XO_NFKD), I<Grapheme_Link> (Gr_Link), +I<Jamo_Short_Name> (JSN), I<Script=Katakana_Or_Hiragana> (sc=Hrkt) + =item Files in the I<To> directory (for serious hackers only) =item SEE ALSO @@ -4241,7 +4303,7 @@ chr(), ord(), pack(), print(), printf(), sort(), sprintf(), unpack() =item Quoted-Printable encoding and decoding -=item Caesarian ciphers +=item Caesarean ciphers =back @@ -4249,7 +4311,7 @@ chr(), ord(), pack(), print(), printf(), sort(), sprintf(), unpack() =item I18N AND L10N -=item MULTI OCTET CHARACTER SETS +=item MULTI-OCTET CHARACTER SETS =item OS ISSUES @@ -4378,12 +4440,14 @@ 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::Distroprefs, -CPAN::FirstTime, CPAN::Kwalify, CPAN::Nox, CPAN::Version, CPANPLUS, -CPANPLUS::Dist::Base, CPANPLUS::Dist::Build, +CPAN::FirstTime, CPAN::Kwalify, CPAN::Meta, CPAN::Meta::Converter, +CPAN::Meta::Feature, CPAN::Meta::History, CPAN::Meta::Prereqs, +CPAN::Meta::Spec, CPAN::Meta::Validator, CPAN::Meta::YAML, CPAN::Nox, +CPAN::Version, CPANPLUS, CPANPLUS::Dist::Base, CPANPLUS::Dist::Build, CPANPLUS::Dist::Build::Constants, CPANPLUS::Dist::Sample, CPANPLUS::Internals::Source::Memory, CPANPLUS::Internals::Source::SQLite, CPANPLUS::Shell::Classic, CPANPLUS::Shell::Default::Plugins::HOWTO, Carp, -Class::ISA, Class::Struct, Compress::Raw::Bzip2, Compress::Raw::Bzip2::FAQ, +Class::Struct, Compress::Raw::Bzip2, Compress::Raw::Bzip2::FAQ, Compress::Raw::Zlib, Compress::Raw::Zlib::FAQ, Compress::Zlib, Config, Cwd, DB, DBM_Filter, DBM_Filter::compress, DBM_Filter::encode, DBM_Filter::int32, DBM_Filter::null, DBM_Filter::utf8, DB_File, @@ -4408,31 +4472,36 @@ 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::Manifest, ExtUtils::Mkbootstrap, ExtUtils::Mksymlists, -ExtUtils::Packlist, ExtUtils::ParseXS, ExtUtils::XSSymSet, -ExtUtils::testlib, Fatal, Fcntl, File::Basename, File::CheckTree, -File::Compare, File::Copy, File::DosGlob, File::Fetch, File::Find, -File::Glob, File::GlobMapper, File::Path, File::Spec, File::Spec::Cygwin, -File::Spec::Epoc, File::Spec::Functions, File::Spec::Mac, File::Spec::OS2, -File::Spec::Unix, File::Spec::VMS, File::Spec::Win32, File::Temp, -File::stat, FileCache, FileHandle, Filter::Simple, Filter::Util::Call, -FindBin, GDBM_File, Getopt::Long, Getopt::Std, Hash::Util, -Hash::Util::FieldHash, I18N::Collate, I18N::LangTags, -I18N::LangTags::Detect, I18N::LangTags::List, I18N::Langinfo, IO, -IO::Compress::Base, IO::Compress::Bzip2, IO::Compress::Deflate, -IO::Compress::FAQ, IO::Compress::Gzip, IO::Compress::RawDeflate, -IO::Compress::Zip, IO::Dir, IO::File, IO::Handle, IO::Pipe, IO::Poll, -IO::Seekable, IO::Select, IO::Socket, IO::Socket::INET, IO::Socket::UNIX, -IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress, -IO::Uncompress::Base, IO::Uncompress::Bunzip2, IO::Uncompress::Gunzip, -IO::Uncompress::Inflate, IO::Uncompress::RawInflate, IO::Uncompress::Unzip, -IO::Zlib, IPC::Cmd, IPC::Msg, IPC::Open2, IPC::Open3, IPC::Semaphore, -IPC::SharedMem, IPC::SysV, List::Util, List::Util::XS, 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, Log::Message::Simple, MIME::Base64, MIME::QuotedPrint, -Math::BigFloat, Math::BigInt, Math::BigInt::Calc, Math::BigInt::CalcEmu, +ExtUtils::MakeMaker::YAML, ExtUtils::Manifest, ExtUtils::Mkbootstrap, +ExtUtils::Mksymlists, ExtUtils::Packlist, ExtUtils::ParseXS, +ExtUtils::XSSymSet, ExtUtils::testlib, Fatal, Fcntl, File::Basename, +File::CheckTree, File::Compare, File::Copy, File::DosGlob, File::Fetch, +File::Find, File::Glob, File::GlobMapper, File::Path, File::Spec, +File::Spec::Cygwin, File::Spec::Epoc, File::Spec::Functions, +File::Spec::Mac, File::Spec::OS2, File::Spec::Unix, File::Spec::VMS, +File::Spec::Win32, File::Temp, File::stat, FileCache, FileHandle, +Filter::Simple, Filter::Util::Call, FindBin, GDBM_File, Getopt::Long, +Getopt::Std, HTTP::Tiny, Hash::Util, Hash::Util::FieldHash, I18N::Collate, +I18N::LangTags, I18N::LangTags::Detect, I18N::LangTags::List, +I18N::Langinfo, IO, IO::Compress::Base, IO::Compress::Bzip2, +IO::Compress::Deflate, IO::Compress::FAQ, IO::Compress::Gzip, +IO::Compress::RawDeflate, IO::Compress::Zip, IO::Dir, IO::File, IO::Handle, +IO::Pipe, IO::Poll, IO::Seekable, IO::Select, IO::Socket, IO::Socket::INET, +IO::Socket::UNIX, IO::Uncompress::AnyInflate, +IO::Uncompress::AnyUncompress, IO::Uncompress::Base, +IO::Uncompress::Bunzip2, IO::Uncompress::Gunzip, IO::Uncompress::Inflate, +IO::Uncompress::RawInflate, IO::Uncompress::Unzip, IO::Zlib, IPC::Cmd, +IPC::Msg, IPC::Open2, IPC::Open3, IPC::Semaphore, IPC::SharedMem, +IPC::SysV, JSON::PP, JSON::PP::Boolean, List::Util, List::Util::XS, +Locale::Codes, Locale::Codes::Changes, Locale::Codes::Country, +Locale::Codes::Currency, Locale::Codes::Language, Locale::Codes::Script, +Locale::Constants, Locale::Country, Locale::Currency, Locale::Language, +Locale::Maketext, Locale::Maketext::Cookbook, Locale::Maketext::Guts, +Locale::Maketext::GutsLoader, Locale::Maketext::Simple, +Locale::Maketext::TPJ13, Locale::Script, Log::Message, +Log::Message::Config, Log::Message::Handlers, Log::Message::Item, +Log::Message::Simple, 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, @@ -4447,20 +4516,21 @@ Module::Build::Platform::Unix, Module::Build::Platform::VMS, Module::Build::Platform::VOS, Module::Build::Platform::Windows, Module::Build::Platform::aix, Module::Build::Platform::cygwin, Module::Build::Platform::darwin, Module::Build::Platform::os2, -Module::CoreList, Module::Load, Module::Load::Conditional, Module::Loaded, +Module::Build::Version, Module::Build::YAML, Module::CoreList, +Module::Load, Module::Load::Conditional, Module::Loaded, Module::Metadata, Module::Pluggable, Module::Pluggable::Object, NDBM_File, NEXT, Net::Cmd, Net::Config, Net::Domain, Net::FTP, Net::NNTP, Net::Netrc, Net::POP3, Net::Ping, Net::SMTP, Net::Time, Net::hostent, Net::libnetFAQ, Net::netent, Net::protoent, Net::servent, O, ODBM_File, Object::Accessor, Opcode, POSIX, -Package::Constants, Params::Check, Parse::CPAN::Meta, PerlIO, +Package::Constants, Params::Check, Parse::CPAN::Meta, Perl::OSType, PerlIO, PerlIO::encoding, PerlIO::scalar, PerlIO::via, PerlIO::via::QuotedPrint, Pod::Checker, Pod::Escapes, Pod::Find, Pod::Functions, Pod::Html, Pod::InputObjects, Pod::LaTeX, Pod::Man, Pod::ParseLink, Pod::ParseUtils, Pod::Parser, Pod::Perldoc, Pod::Perldoc::BaseTo, Pod::Perldoc::GetOptsOO, Pod::Perldoc::ToChecker, Pod::Perldoc::ToMan, Pod::Perldoc::ToNroff, Pod::Perldoc::ToPod, Pod::Perldoc::ToRtf, Pod::Perldoc::ToText, -Pod::Perldoc::ToTk, Pod::Perldoc::ToXml, Pod::PlainText, Pod::Plainer, -Pod::Select, Pod::Simple, Pod::Simple::Checker, Pod::Simple::Debug, +Pod::Perldoc::ToTk, Pod::Perldoc::ToXml, Pod::PlainText, Pod::Select, +Pod::Simple, Pod::Simple::Checker, Pod::Simple::Debug, Pod::Simple::DumpAsText, Pod::Simple::DumpAsXML, Pod::Simple::HTML, Pod::Simple::HTMLBatch, Pod::Simple::LinkSection, Pod::Simple::Methody, Pod::Simple::PullParser, Pod::Simple::PullParserEndToken, @@ -4470,8 +4540,8 @@ Pod::Simple::SimpleTree, Pod::Simple::Subclassing, Pod::Simple::Text, Pod::Simple::TextContent, Pod::Simple::XHTML, Pod::Simple::XMLOutStream, Pod::Text, Pod::Text::Color, 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, -TAP::Base, TAP::Formatter::Color, TAP::Formatter::Console, +Storable, Symbol, Sys::Hostname, Sys::Syslog, Sys::Syslog::Win32, +TAP::Base, TAP::Formatter::Base, TAP::Formatter::Color, TAP::Formatter::Console, TAP::Formatter::Console::ParallelSession, TAP::Formatter::Console::Session, TAP::Formatter::File, TAP::Formatter::File::Session, TAP::Formatter::Session, TAP::Harness, @@ -4486,21 +4556,26 @@ TAP::Parser::Result::Unknown, TAP::Parser::Result::Version, TAP::Parser::Result::YAML, TAP::Parser::ResultFactory, TAP::Parser::Scheduler, TAP::Parser::Scheduler::Job, TAP::Parser::Scheduler::Spinner, 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::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::StdHandle, Tie::SubstrHash, Time::HiRes, Time::Local, Time::Piece, -Time::Seconds, Time::gmtime, Time::localtime, Time::tm, UNIVERSAL, -Unicode::Collate, Unicode::Normalize, Unicode::UCD, User::grent, -User::pwent, VMS::DCLsym, VMS::Stdio, Win32, Win32API::File, Win32CORE, -XS::APItest, XS::APItest::KeywordRPN, XS::Typemap, XSLoader, -version::Internals +TAP::Parser::SourceHandler, TAP::Parser::SourceHandler::Executable, +TAP::Parser::SourceHandler::File, TAP::Parser::SourceHandler::Handle, +TAP::Parser::SourceHandler::Perl, TAP::Parser::SourceHandler::RawTAP, +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::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::StdHandle, Tie::SubstrHash, Time::HiRes, Time::Local, +Time::Piece, Time::Seconds, Time::gmtime, Time::localtime, Time::tm, +UNIVERSAL, Unicode::Collate, Unicode::Collate::CJK::Big5, +Unicode::Collate::CJK::GB2312, Unicode::Collate::CJK::JISX0208, +Unicode::Collate::CJK::Korean, Unicode::Collate::CJK::Pinyin, +Unicode::Collate::CJK::Stroke, Unicode::Collate::Locale, +Unicode::Normalize, Unicode::UCD, User::grent, User::pwent, VMS::DCLsym, +VMS::Stdio, Version::Requirements, Win32, Win32API::File, Win32CORE, +XS::APItest, XS::Typemap, XSLoader, version::Internals =item Extension Modules @@ -4760,7 +4835,7 @@ L<pod2html|pod2html> and L<pod2latex|pod2latex>, L<pod2usage|pod2usage>, L<podselect|podselect>, L<podchecker|podchecker>, L<splain|splain>, L<roffitall|roffitall> -=item Convertors +=item Converters L<a2p|a2p>, L<s2p|s2p> and L<psed>, L<find2perl|find2perl> @@ -4776,7 +4851,7 @@ L<dprofpp|dprofpp>, L<prove>, L<corelist> =item General tools -L<piconv>, L<ptar>, L<ptardiff>, L<shasum> +L<piconv>, L<ptar>, L<ptardiff>, L<ptargrep>, L<shasum> =item Installation @@ -4806,7 +4881,7 @@ B::Lint, B::Deparse, B::Xref =over 4 -=item The Cross Referencing Back End +=item The Cross-Referencing Back End i, &, s, r @@ -4890,14 +4965,15 @@ broadcast, BSD, bucket, buffer, built-in, bundle, byte, bytecode =item C C, C preprocessor, call by reference, call by value, callback, canonical, -capturing, character, character class, character property, circumfix -operator, class, class method, client, cloister, closure, cluster, CODE, -code generator, code subpattern, collating sequence, command, command -buffering, command name, command-line arguments, comment, compilation unit, -compile phase, compile time, compiler, composer, concatenation, -conditional, connection, construct, constructor, context, continuation, -core dump, CPAN, cracker, current package, current working directory, -currently selected output channel, CV +capture buffer, capture group, capturing, character, character class, +character property, circumfix operator, class, class method, client, +cloister, closure, cluster, CODE, code generator, code point, code +subpattern, collating sequence, command, command buffering, command name, +command-line arguments, comment, compilation unit, compile phase, compile +time, compiler, composer, concatenation, conditional, connection, +construct, constructor, context, continuation, core dump, CPAN, cracker, +current package, current working directory, currently selected output +channel, CV =item D @@ -4919,13 +4995,12 @@ file, execute, execute bit, exit status, export, expression, extension false, FAQ, fatal error, field, FIFO, file, file descriptor, file test operator, fileglob, filehandle, filename, filesystem, filter, flag, floating point, flush, FMTEYEWTK, fork, formal arguments, format, freely -available, freely redistributable, freeware, function, funny character, -garbage collection +available, freely redistributable, freeware, function, funny character =item G -GID, glob, global, global destruction, glue language, granularity, greedy, -grep, group, GV +garbage collection, GID, glob, global, global destruction, glue language, +granularity, greedy, grep, group, GV =item H @@ -4937,7 +5012,7 @@ document, hexadecimal, home directory, host, hubris, HV identifier, impatience, implementation, import, increment, indexing, indirect filehandle, indirect object, indirect object slot, indirection, infix, inheritance, instance, instance variable, integer, interface, -interpolation, interpreter, invocant, invocation, I/O, IO, IP, IPC, is-a, +interpolation, interpreter, invocand, invocation, I/O, IO, IP, IPC, is-a, iteration, iterator, IV =item J @@ -4972,8 +5047,8 @@ list, null string, numeric context, NV, nybble =item O object, octal, offset, one-liner, open source software, operand, operating -system, operator, operator overloading, options, overloading, overriding, -owner +system, operator, operator overloading, options, ordinal, overloading, +overriding, owner =item P @@ -5091,8 +5166,6 @@ program =back -=item Embedding Perl under Win32 - =item Hiding Perl_ =item MORAL @@ -5119,24 +5192,24 @@ program =item Frame Listing Output Examples -=item Debugging regular expressions +=item Debugging Regular Expressions =over 4 -=item Compile-time output +=item Compile-time Output C<anchored> I<STRING> C<at> I<POS>, C<floating> I<STRING> C<at> I<POS1..POS2>, C<matching floating/anchored>, C<minlen>, C<stclass> I<TYPE>, C<noscan>, C<isall>, C<GPOS>, C<plus>, C<implicit>, C<with eval>, C<anchored(TYPE)> -=item Types of nodes +=item Types of Nodes -=item Run-time output +=item Run-time Output =back -=item Debugging Perl memory usage +=item Debugging Perl Memory Usage =over 4 @@ -5326,6 +5399,8 @@ SBRKed/SBRKs:CONTINUOUS>, C<pad: 0>, C<heads: 2192>, C<chain: 0>, C<tail: =item The INCLUDE: Keyword +=item The INCLUDE_COMMAND: Keyword + =item The CASE: Keyword =item The & Unary Operator @@ -5495,6 +5570,11 @@ save_hptr(HV **hptr)> =item Pluggable runops +=item Compile-time scope hooks + +C<void bhk_start(pTHX_ int full)>, C<void bhk_pre_end(pTHX_ OP **o)>, +C<void bhk_post_end(pTHX_ OP **o)>, C<void bhk_eval(pTHX_ OP *const o)> + =back =item Examining internal data structures with the C<dump> functions @@ -5553,6 +5633,10 @@ A, p, d, s, n, r, f, M, o, x, m, X, E, b, others =item Custom Operators +xop_name, xop_desc, xop_class, OA_BASEOP, OA_UNOP, OA_BINOP, OA_LOGOP, +OA_LISTOP, OA_PMOP, OA_SVOP, OA_PADOP, OA_PVOP_OR_SVOP, OA_LOOP, OA_COP, +xop_peep + =item AUTHORS =item SEE ALSO @@ -5565,7 +5649,7 @@ A, p, d, s, n, r, f, M, o, x, m, X, E, b, others =item DESCRIPTION -An Error Handler, An Event Driven Program +An Error Handler, An Event-Driven Program =item THE CALL_ FUNCTIONS @@ -5597,17 +5681,17 @@ call_sv, call_pv, call_method, call_argv =over 4 -=item No Parameters, Nothing returned +=item No Parameters, Nothing Returned =item Passing Parameters =item Returning a Scalar -=item Returning a list of values +=item Returning a List of Values -=item Returning a list in a scalar context +=item Returning a List in a Scalar Context -=item Returning Data from Perl via the parameter list +=item Returning Data from Perl via the Parameter List =item Using G_EVAL @@ -5621,9 +5705,9 @@ call_sv, call_pv, call_method, call_argv =item Using GIMME_V -=item Using Perl to dispose of temporaries +=item Using Perl to Dispose of Temporaries -=item Strategies for storing Callback Context Information +=item Strategies for Storing Callback Context Information 1. Ignore the problem - Allow only 1 callback, 2. Create a sequence of callbacks - hard wired limit, 3. Use a parameter to map to the Perl @@ -5631,7 +5715,7 @@ callback =item Alternate Stack Manipulation -=item Creating and calling an anonymous subroutine in C +=item Creating and Calling an Anonymous Subroutine in C =back @@ -5676,9 +5760,9 @@ resolve, name, length, kflags, hash =item comp C</m> - RXf_PMf_MULTILINE, C</s> - RXf_PMf_SINGLELINE, C</i> - -RXf_PMf_FOLD, C</x> - RXf_PMf_EXTENDED, C</p> - RXf_PMf_KEEPCOPY, -RXf_PMf_LOCALE, RXf_UTF8, RXf_SPLIT, RXf_SKIPWHITE, RXf_START_ONLY, -RXf_WHITE, RXf_NULL +RXf_PMf_FOLD, C</x> - RXf_PMf_EXTENDED, C</p> - RXf_PMf_KEEPCOPY, Character +set, RXf_UTF8, RXf_SPLIT, RXf_SKIPWHITE, RXf_START_ONLY, RXf_WHITE, +RXf_NULL =item exec @@ -5838,16 +5922,48 @@ call_argv X<call_argv>, call_method X<call_method>, call_pv X<call_pv>, call_sv X<call_sv>, ENTER X<ENTER>, eval_pv X<eval_pv>, eval_sv X<eval_sv>, FREETMPS X<FREETMPS>, LEAVE X<LEAVE>, SAVETMPS X<SAVETMPS> +=item Character case changing + +toLOWER X<toLOWER>, toUPPER X<toUPPER> + =item Character classes -isALNUM X<isALNUM>, isALPHA X<isALPHA>, isDIGIT X<isDIGIT>, isLOWER -X<isLOWER>, isSPACE X<isSPACE>, isUPPER X<isUPPER>, toLOWER X<toLOWER>, -toUPPER X<toUPPER> +isALPHA X<isALPHA>, isASCII X<isASCII>, isDIGIT X<isDIGIT>, isLOWER +X<isLOWER>, isOCTAL X<isOCTAL>, isSPACE X<isSPACE>, isUPPER X<isUPPER>, +isWORDCHAR X<isWORDCHAR>, isXDIGIT X<isXDIGIT> =item Cloning an interpreter perl_clone X<perl_clone> +=item Compile-time scope hooks + +BhkDISABLE X<BhkDISABLE>, BhkENABLE X<BhkENABLE>, BhkENTRY_set +X<BhkENTRY_set>, blockhook_register X<blockhook_register> + +=item COP Hint Hashes + +cophh_2hv X<cophh_2hv>, cophh_copy X<cophh_copy>, cophh_delete_pv +X<cophh_delete_pv>, cophh_delete_pvn X<cophh_delete_pvn>, cophh_delete_pvs +X<cophh_delete_pvs>, cophh_delete_sv X<cophh_delete_sv>, cophh_fetch_pv +X<cophh_fetch_pv>, cophh_fetch_pvn X<cophh_fetch_pvn>, cophh_fetch_pvs +X<cophh_fetch_pvs>, cophh_fetch_sv X<cophh_fetch_sv>, cophh_free +X<cophh_free>, cophh_new_empty X<cophh_new_empty>, cophh_store_pv +X<cophh_store_pv>, cophh_store_pvn X<cophh_store_pvn>, cophh_store_pvs +X<cophh_store_pvs>, cophh_store_sv X<cophh_store_sv> + +=item COP Hint Reading + +cop_hints_2hv X<cop_hints_2hv>, cop_hints_fetch_pv X<cop_hints_fetch_pv>, +cop_hints_fetch_pvn X<cop_hints_fetch_pvn>, cop_hints_fetch_pvs +X<cop_hints_fetch_pvs>, cop_hints_fetch_sv X<cop_hints_fetch_sv> + +=item Custom Operators + +custom_op_register X<custom_op_register>, custom_op_xop X<custom_op_xop>, +XopDISABLE X<XopDISABLE>, XopENABLE X<XopENABLE>, XopENTRY X<XopENTRY>, +XopENTRY_set X<XopENTRY_set>, XopFLAGS X<XopFLAGS> + =item CV Manipulation Functions CvSTASH X<CvSTASH>, get_cv X<get_cv>, get_cvn_flags X<get_cvn_flags> @@ -5855,9 +5971,10 @@ CvSTASH X<CvSTASH>, get_cv X<get_cv>, get_cvn_flags X<get_cvn_flags> =item Embedding Functions cv_undef X<cv_undef>, load_module X<load_module>, nothreadhook -X<nothreadhook>, perl_alloc X<perl_alloc>, perl_construct -X<perl_construct>, perl_destruct X<perl_destruct>, perl_free X<perl_free>, -perl_parse X<perl_parse>, perl_run X<perl_run>, require_pv X<require_pv> +X<nothreadhook>, pad_findmy X<pad_findmy>, pad_sv X<pad_sv>, perl_alloc +X<perl_alloc>, perl_construct X<perl_construct>, perl_destruct +X<perl_destruct>, perl_free X<perl_free>, perl_parse X<perl_parse>, +perl_run X<perl_run>, require_pv X<require_pv> =item Functions in file dump.c @@ -5865,6 +5982,7 @@ pv_display X<pv_display>, pv_escape X<pv_escape>, pv_pretty X<pv_pretty> =item Functions in file mathoms.c +custom_op_desc X<custom_op_desc>, custom_op_name X<custom_op_name>, gv_fetchmethod X<gv_fetchmethod>, pack_cat X<pack_cat>, sv_2pvbyte_nolen X<sv_2pvbyte_nolen>, sv_2pvutf8_nolen X<sv_2pvutf8_nolen>, sv_2pv_nolen X<sv_2pv_nolen>, sv_catpvn_mg X<sv_catpvn_mg>, sv_catsv_mg X<sv_catsv_mg>, @@ -5875,6 +5993,10 @@ X<sv_pvn>, sv_pvutf8 X<sv_pvutf8>, sv_pvutf8n X<sv_pvutf8n>, sv_taint X<sv_taint>, sv_unref X<sv_unref>, sv_usepvn X<sv_usepvn>, sv_usepvn_mg X<sv_usepvn_mg>, sv_uv X<sv_uv>, unpack_str X<unpack_str> +=item Functions in file op.c + +op_contextualize X<op_contextualize> + =item Functions in file perl.h PERL_SYS_INIT X<PERL_SYS_INIT>, PERL_SYS_INIT3 X<PERL_SYS_INIT3>, @@ -5882,7 +6004,7 @@ PERL_SYS_TERM X<PERL_SYS_TERM> =item Functions in file pp_ctl.c -find_runcv X<find_runcv> +caller_cx X<caller_cx>, find_runcv X<find_runcv> =item Functions in file pp_pack.c @@ -5892,6 +6014,14 @@ packlist X<packlist>, unpackstring X<unpackstring> setdefout X<setdefout> +=item Functions in file utf8.h + +ibcmp_utf8 X<ibcmp_utf8> + +=item Functions in file util.h + +ibcmp X<ibcmp>, ibcmp_locale X<ibcmp_locale> + =item Global Variables PL_keyword_plugin X<PL_keyword_plugin> @@ -5913,38 +6043,45 @@ 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>, 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>, -hv_fetch_ent X<hv_fetch_ent>, hv_iterinit X<hv_iterinit>, hv_iterkey -X<hv_iterkey>, hv_iterkeysv X<hv_iterkeysv>, hv_iternext X<hv_iternext>, -hv_iternextsv X<hv_iternextsv>, hv_iternext_flags X<hv_iternext_flags>, -hv_iterval X<hv_iterval>, hv_magic X<hv_magic>, hv_scalar X<hv_scalar>, -hv_store X<hv_store>, hv_stores X<hv_stores>, hv_store_ent X<hv_store_ent>, -hv_undef X<hv_undef>, newHV X<newHV> +X<HeVAL>, HvENAME X<HvENAME>, HvNAME X<HvNAME>, hv_assert X<hv_assert>, +hv_clear X<hv_clear>, hv_clear_placeholders X<hv_clear_placeholders>, +hv_copy_hints_hv X<hv_copy_hints_hv>, hv_delete X<hv_delete>, hv_delete_ent +X<hv_delete_ent>, hv_exists X<hv_exists>, hv_exists_ent X<hv_exists_ent>, +hv_fetch X<hv_fetch>, hv_fetchs X<hv_fetchs>, hv_fetch_ent X<hv_fetch_ent>, +hv_fill X<hv_fill>, hv_iterinit X<hv_iterinit>, hv_iterkey X<hv_iterkey>, +hv_iterkeysv X<hv_iterkeysv>, hv_iternext X<hv_iternext>, hv_iternextsv +X<hv_iternextsv>, hv_iternext_flags X<hv_iternext_flags>, hv_iterval +X<hv_iterval>, hv_magic X<hv_magic>, hv_scalar X<hv_scalar>, hv_store +X<hv_store>, hv_stores X<hv_stores>, hv_store_ent X<hv_store_ent>, hv_undef +X<hv_undef>, newHV X<newHV> =item Lexer interface lex_bufutf8 X<lex_bufutf8>, lex_discard_to X<lex_discard_to>, lex_grow_linestr X<lex_grow_linestr>, lex_next_chunk X<lex_next_chunk>, lex_peek_unichar X<lex_peek_unichar>, lex_read_space X<lex_read_space>, -lex_read_to X<lex_read_to>, lex_read_unichar X<lex_read_unichar>, -lex_stuff_pvn X<lex_stuff_pvn>, lex_stuff_sv X<lex_stuff_sv>, lex_unstuff -X<lex_unstuff>, PL_parser X<PL_parser>, PL_parser-E<gt>bufend -X<PL_parser-E<gt>bufend>, PL_parser-E<gt>bufptr X<PL_parser-E<gt>bufptr>, -PL_parser-E<gt>linestart X<PL_parser-E<gt>linestart>, -PL_parser-E<gt>linestr X<PL_parser-E<gt>linestr> +lex_read_to X<lex_read_to>, lex_read_unichar X<lex_read_unichar>, lex_start +X<lex_start>, lex_stuff_pv X<lex_stuff_pv>, lex_stuff_pvn X<lex_stuff_pvn>, +lex_stuff_pvs X<lex_stuff_pvs>, lex_stuff_sv X<lex_stuff_sv>, lex_unstuff +X<lex_unstuff>, parse_arithexpr X<parse_arithexpr>, parse_barestmt +X<parse_barestmt>, parse_block X<parse_block>, parse_fullexpr +X<parse_fullexpr>, parse_fullstmt X<parse_fullstmt>, parse_label +X<parse_label>, parse_listexpr X<parse_listexpr>, parse_stmtseq +X<parse_stmtseq>, parse_termexpr X<parse_termexpr>, PL_parser X<PL_parser>, +PL_parser-E<gt>bufend X<PL_parser-E<gt>bufend>, PL_parser-E<gt>bufptr +X<PL_parser-E<gt>bufptr>, PL_parser-E<gt>linestart +X<PL_parser-E<gt>linestart>, PL_parser-E<gt>linestr +X<PL_parser-E<gt>linestr> =item Magical Functions -mg_clear X<mg_clear>, mg_copy X<mg_copy>, mg_find X<mg_find>, mg_free -X<mg_free>, mg_get X<mg_get>, mg_length X<mg_length>, mg_magical -X<mg_magical>, mg_set X<mg_set>, SvGETMAGIC X<SvGETMAGIC>, SvLOCK -X<SvLOCK>, SvSETMAGIC X<SvSETMAGIC>, SvSetMagicSV X<SvSetMagicSV>, -SvSetMagicSV_nosteal X<SvSetMagicSV_nosteal>, SvSetSV X<SvSetSV>, -SvSetSV_nosteal X<SvSetSV_nosteal>, SvSHARE X<SvSHARE>, SvUNLOCK -X<SvUNLOCK> +mg_clear X<mg_clear>, mg_copy X<mg_copy>, mg_find X<mg_find>, mg_findext +X<mg_findext>, mg_free X<mg_free>, mg_free_type X<mg_free_type>, mg_get +X<mg_get>, mg_length X<mg_length>, mg_magical X<mg_magical>, mg_set +X<mg_set>, SvGETMAGIC X<SvGETMAGIC>, SvLOCK X<SvLOCK>, SvSETMAGIC +X<SvSETMAGIC>, SvSetMagicSV X<SvSetMagicSV>, SvSetMagicSV_nosteal +X<SvSetMagicSV_nosteal>, SvSetSV X<SvSetSV>, SvSetSV_nosteal +X<SvSetSV_nosteal>, SvSHARE X<SvSHARE>, SvUNLOCK X<SvUNLOCK> =item Memory Management @@ -5953,20 +6090,22 @@ Newxc X<Newxc>, Newxz X<Newxz>, Poison X<Poison>, PoisonFree X<PoisonFree>, PoisonNew X<PoisonNew>, PoisonWith X<PoisonWith>, Renew X<Renew>, Renewc X<Renewc>, Safefree X<Safefree>, savepv X<savepv>, savepvn X<savepvn>, savepvs X<savepvs>, savesharedpv X<savesharedpv>, savesharedpvn -X<savesharedpvn>, savesvpv X<savesvpv>, StructCopy X<StructCopy>, Zero +X<savesharedpvn>, savesharedpvs X<savesharedpvs>, savesharedsvpv +X<savesharedsvpv>, savesvpv X<savesvpv>, StructCopy X<StructCopy>, Zero X<Zero>, ZeroD X<ZeroD> =item Miscellaneous Functions -fbm_compile X<fbm_compile>, fbm_instr X<fbm_instr>, form X<form>, getcwd_sv -X<getcwd_sv>, my_snprintf X<my_snprintf>, my_sprintf X<my_sprintf>, -my_vsnprintf X<my_vsnprintf>, new_version X<new_version>, prescan_version -X<prescan_version>, scan_version X<scan_version>, strEQ X<strEQ>, strGE -X<strGE>, strGT X<strGT>, strLE X<strLE>, strLT X<strLT>, strNE X<strNE>, -strnEQ X<strnEQ>, strnNE X<strnNE>, sv_destroyable X<sv_destroyable>, -sv_nosharing X<sv_nosharing>, upg_version X<upg_version>, vcmp X<vcmp>, -vnormal X<vnormal>, vnumify X<vnumify>, vstringify X<vstringify>, vverify -X<vverify> +fbm_compile X<fbm_compile>, fbm_instr X<fbm_instr>, foldEQ X<foldEQ>, +foldEQ_locale X<foldEQ_locale>, form X<form>, getcwd_sv X<getcwd_sv>, mess +X<mess>, mess_sv X<mess_sv>, my_snprintf X<my_snprintf>, my_sprintf +X<my_sprintf>, my_vsnprintf X<my_vsnprintf>, new_version X<new_version>, +prescan_version X<prescan_version>, scan_version X<scan_version>, strEQ +X<strEQ>, strGE X<strGE>, strGT X<strGT>, strLE X<strLE>, strLT X<strLT>, +strNE X<strNE>, strnEQ X<strnEQ>, strnNE X<strnNE>, sv_destroyable +X<sv_destroyable>, sv_nosharing X<sv_nosharing>, upg_version +X<upg_version>, vcmp X<vcmp>, vmess X<vmess>, vnormal X<vnormal>, vnumify +X<vnumify>, vstringify X<vstringify>, vverify X<vverify> =item MRO Functions @@ -5985,19 +6124,34 @@ grok_numeric_radix X<grok_numeric_radix>, grok_oct X<grok_oct>, Perl_signbit X<Perl_signbit>, scan_bin X<scan_bin>, scan_hex X<scan_hex>, scan_oct X<scan_oct> -=item Optree Manipulation Functions +=item Optree construction -cv_const_sv X<cv_const_sv>, newCONSTSUB X<newCONSTSUB>, newXS X<newXS> +newASSIGNOP X<newASSIGNOP>, newBINOP X<newBINOP>, newCONDOP X<newCONDOP>, +newFOROP X<newFOROP>, newGIVENOP X<newGIVENOP>, newGVOP X<newGVOP>, +newLISTOP X<newLISTOP>, newLOGOP X<newLOGOP>, newLOOPEX X<newLOOPEX>, +newLOOPOP X<newLOOPOP>, newNULLLIST X<newNULLLIST>, newOP X<newOP>, +newPADOP X<newPADOP>, newPMOP X<newPMOP>, newPVOP X<newPVOP>, newRANGE +X<newRANGE>, newSLICEOP X<newSLICEOP>, newSTATEOP X<newSTATEOP>, newSVOP +X<newSVOP>, newUNOP X<newUNOP>, newWHENOP X<newWHENOP>, newWHILEOP +X<newWHILEOP> -=item Pad Data Structures +=item Optree Manipulation Functions -pad_findmy X<pad_findmy>, pad_sv X<pad_sv> +ck_entersub_args_list X<ck_entersub_args_list>, ck_entersub_args_proto +X<ck_entersub_args_proto>, ck_entersub_args_proto_or_list +X<ck_entersub_args_proto_or_list>, cv_const_sv X<cv_const_sv>, +cv_get_call_checker X<cv_get_call_checker>, cv_set_call_checker +X<cv_set_call_checker>, LINKLIST X<LINKLIST>, newCONSTSUB X<newCONSTSUB>, +newXS X<newXS>, op_append_elem X<op_append_elem>, op_append_list +X<op_append_list>, OP_CLASS X<OP_CLASS>, OP_DESC X<OP_DESC>, op_linklist +X<op_linklist>, op_lvalue X<op_lvalue>, OP_NAME X<OP_NAME>, op_prepend_elem +X<op_prepend_elem>, op_scope X<op_scope>, rv2cv_op_cv X<rv2cv_op_cv> =item Per-Interpreter Variables PL_modglobal X<PL_modglobal>, PL_na X<PL_na>, PL_opfreehook -X<PL_opfreehook>, PL_sv_no X<PL_sv_no>, PL_sv_undef X<PL_sv_undef>, -PL_sv_yes X<PL_sv_yes> +X<PL_opfreehook>, PL_peepp X<PL_peepp>, PL_rpeepp X<PL_rpeepp>, PL_sv_no +X<PL_sv_no>, PL_sv_undef X<PL_sv_undef>, PL_sv_yes X<PL_sv_yes> =item REGEXP Functions @@ -6046,34 +6200,36 @@ SvIVx X<SvIVx>, SvIV_nomg X<SvIV_nomg>, SvIV_set X<SvIV_set>, SvLEN X<SvLEN>, SvLEN_set X<SvLEN_set>, SvMAGIC_set X<SvMAGIC_set>, SvNIOK X<SvNIOK>, SvNIOKp X<SvNIOKp>, SvNIOK_off X<SvNIOK_off>, SvNOK X<SvNOK>, SvNOKp X<SvNOKp>, SvNOK_off X<SvNOK_off>, SvNOK_on X<SvNOK_on>, SvNOK_only -X<SvNOK_only>, SvNV X<SvNV>, SvNVX X<SvNVX>, SvNVx X<SvNVx>, SvNV_set -X<SvNV_set>, SvOK X<SvOK>, SvOOK X<SvOOK>, 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 -X<SvREFCNT_inc_simple>, SvREFCNT_inc_simple_NN X<SvREFCNT_inc_simple_NN>, -SvREFCNT_inc_simple_void X<SvREFCNT_inc_simple_void>, -SvREFCNT_inc_simple_void_NN X<SvREFCNT_inc_simple_void_NN>, -SvREFCNT_inc_void X<SvREFCNT_inc_void>, SvREFCNT_inc_void_NN -X<SvREFCNT_inc_void_NN>, SvROK X<SvROK>, SvROK_off X<SvROK_off>, SvROK_on -X<SvROK_on>, SvRV X<SvRV>, SvRV_set X<SvRV_set>, SvSTASH X<SvSTASH>, -SvSTASH_set X<SvSTASH_set>, SvTAINT X<SvTAINT>, SvTAINTED X<SvTAINTED>, -SvTAINTED_off X<SvTAINTED_off>, SvTAINTED_on X<SvTAINTED_on>, SvTRUE -X<SvTRUE>, SvTYPE X<SvTYPE>, SvUOK X<SvUOK>, SvUPGRADE X<SvUPGRADE>, SvUTF8 -X<SvUTF8>, SvUTF8_off X<SvUTF8_off>, SvUTF8_on X<SvUTF8_on>, SvUV X<SvUV>, -SvUVX X<SvUVX>, SvUVx X<SvUVx>, SvUV_nomg X<SvUV_nomg>, SvUV_set -X<SvUV_set>, SvVOK X<SvVOK>, sv_catpvn_nomg X<sv_catpvn_nomg>, -sv_catsv_nomg X<sv_catsv_nomg>, sv_derived_from X<sv_derived_from>, sv_does -X<sv_does>, sv_report_used X<sv_report_used>, sv_setsv_nomg -X<sv_setsv_nomg>, sv_utf8_upgrade_nomg X<sv_utf8_upgrade_nomg> +X<SvNOK_only>, SvNV X<SvNV>, SvNVX X<SvNVX>, SvNVx X<SvNVx>, SvNV_nomg +X<SvNV_nomg>, SvNV_set 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_nomg_nolen +X<SvPV_nomg_nolen>, SvPV_set X<SvPV_set>, SvREFCNT X<SvREFCNT>, +SvREFCNT_dec X<SvREFCNT_dec>, SvREFCNT_inc X<SvREFCNT_inc>, SvREFCNT_inc_NN +X<SvREFCNT_inc_NN>, SvREFCNT_inc_simple X<SvREFCNT_inc_simple>, +SvREFCNT_inc_simple_NN X<SvREFCNT_inc_simple_NN>, SvREFCNT_inc_simple_void +X<SvREFCNT_inc_simple_void>, SvREFCNT_inc_simple_void_NN +X<SvREFCNT_inc_simple_void_NN>, SvREFCNT_inc_void X<SvREFCNT_inc_void>, +SvREFCNT_inc_void_NN X<SvREFCNT_inc_void_NN>, SvROK X<SvROK>, SvROK_off +X<SvROK_off>, SvROK_on X<SvROK_on>, SvRV X<SvRV>, SvRV_set X<SvRV_set>, +SvSTASH X<SvSTASH>, SvSTASH_set X<SvSTASH_set>, SvTAINT X<SvTAINT>, +SvTAINTED X<SvTAINTED>, SvTAINTED_off X<SvTAINTED_off>, SvTAINTED_on +X<SvTAINTED_on>, SvTRUE X<SvTRUE>, SvTRUE_nomg X<SvTRUE_nomg>, SvTYPE +X<SvTYPE>, SvUOK X<SvUOK>, SvUPGRADE X<SvUPGRADE>, SvUTF8 X<SvUTF8>, +SvUTF8_off X<SvUTF8_off>, SvUTF8_on X<SvUTF8_on>, SvUV X<SvUV>, SvUVX +X<SvUVX>, SvUVx X<SvUVx>, SvUV_nomg X<SvUV_nomg>, SvUV_set X<SvUV_set>, +SvVOK X<SvVOK>, sv_catpvn_nomg X<sv_catpvn_nomg>, sv_catpv_nomg +X<sv_catpv_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>, sv_utf8_upgrade_nomg +X<sv_utf8_upgrade_nomg> =item SV-Body Allocation @@ -6082,56 +6238,65 @@ X<newSV>, newSVhek X<newSVhek>, newSViv X<newSViv>, newSVnv X<newSVnv>, newSVpv X<newSVpv>, newSVpvf X<newSVpvf>, newSVpvn X<newSVpvn>, 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 -X<sv_2mortal>, sv_2nv X<sv_2nv>, sv_2pvbyte X<sv_2pvbyte>, sv_2pvutf8 +X<newSVpvs_share>, newSVpv_share X<newSVpv_share>, newSVrv X<newSVrv>, +newSVsv X<newSVsv>, newSVuv X<newSVuv>, newSV_type X<newSV_type>, sv_2bool +X<sv_2bool>, sv_2bool_flags X<sv_2bool_flags>, sv_2cv X<sv_2cv>, sv_2io +X<sv_2io>, sv_2iv_flags X<sv_2iv_flags>, sv_2mortal X<sv_2mortal>, +sv_2nv_flags X<sv_2nv_flags>, sv_2pvbyte X<sv_2pvbyte>, sv_2pvutf8 X<sv_2pvutf8>, sv_2pv_flags X<sv_2pv_flags>, sv_2uv_flags X<sv_2uv_flags>, sv_backoff X<sv_backoff>, sv_bless X<sv_bless>, sv_catpv X<sv_catpv>, sv_catpvf X<sv_catpvf>, sv_catpvf_mg X<sv_catpvf_mg>, sv_catpvn X<sv_catpvn>, sv_catpvn_flags X<sv_catpvn_flags>, sv_catpvs X<sv_catpvs>, +sv_catpvs_flags X<sv_catpvs_flags>, sv_catpvs_mg X<sv_catpvs_mg>, +sv_catpvs_nomg X<sv_catpvs_nomg>, sv_catpv_flags X<sv_catpv_flags>, sv_catpv_mg X<sv_catpv_mg>, sv_catsv X<sv_catsv>, sv_catsv_flags X<sv_catsv_flags>, sv_chop X<sv_chop>, sv_clear X<sv_clear>, sv_cmp -X<sv_cmp>, sv_cmp_locale X<sv_cmp_locale>, sv_collxfrm X<sv_collxfrm>, -sv_copypv X<sv_copypv>, sv_dec X<sv_dec>, sv_eq X<sv_eq>, -sv_force_normal_flags X<sv_force_normal_flags>, sv_free X<sv_free>, sv_gets -X<sv_gets>, sv_grow X<sv_grow>, sv_inc X<sv_inc>, sv_insert X<sv_insert>, -sv_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_pos_u2b_flags -X<sv_pos_u2b_flags>, 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_cmp>, sv_cmp_flags X<sv_cmp_flags>, sv_cmp_locale X<sv_cmp_locale>, +sv_cmp_locale_flags X<sv_cmp_locale_flags>, sv_collxfrm X<sv_collxfrm>, +sv_collxfrm_flags X<sv_collxfrm_flags>, sv_copypv X<sv_copypv>, sv_dec +X<sv_dec>, sv_dec_nomg X<sv_dec_nomg>, sv_eq X<sv_eq>, sv_eq_flags +X<sv_eq_flags>, 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_inc_nomg X<sv_inc_nomg>, sv_insert X<sv_insert>, 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_pos_u2b_flags X<sv_pos_u2b_flags>, +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>, +X<sv_setpvs>, sv_setpvs_mg X<sv_setpvs_mg>, 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_pvs +X<sv_setref_pvs>, 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_utf8_upgrade_nomg X<sv_utf8_upgrade_nomg>, 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> +X<sv_true>, sv_unmagic X<sv_unmagic>, sv_unmagicext X<sv_unmagicext>, +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_utf8_upgrade_nomg +X<sv_utf8_upgrade_nomg>, sv_vcatpvf X<sv_vcatpvf>, sv_vcatpvfn +X<sv_vcatpvfn>, sv_vcatpvf_mg X<sv_vcatpvf_mg>, sv_vsetpvf X<sv_vsetpvf>, +sv_vsetpvfn X<sv_vsetpvfn>, sv_vsetpvf_mg X<sv_vsetpvf_mg> =item Unicode Support -bytes_from_utf8 X<bytes_from_utf8>, bytes_to_utf8 X<bytes_to_utf8>, -ibcmp_utf8 X<ibcmp_utf8>, is_ascii_string X<is_ascii_string>, is_utf8_char -X<is_utf8_char>, is_utf8_string X<is_utf8_string>, is_utf8_string_loc -X<is_utf8_string_loc>, is_utf8_string_loclen X<is_utf8_string_loclen>, -pv_uni_display X<pv_uni_display>, sv_cat_decode X<sv_cat_decode>, -sv_recode_to_utf8 X<sv_recode_to_utf8>, sv_uni_display X<sv_uni_display>, -to_utf8_case X<to_utf8_case>, to_utf8_fold X<to_utf8_fold>, to_utf8_lower +bytes_cmp_utf8 X<bytes_cmp_utf8>, bytes_from_utf8 X<bytes_from_utf8>, +bytes_to_utf8 X<bytes_to_utf8>, foldEQ_utf8 X<foldEQ_utf8>, is_ascii_string +X<is_ascii_string>, is_utf8_char X<is_utf8_char>, is_utf8_string +X<is_utf8_string>, is_utf8_string_loc X<is_utf8_string_loc>, +is_utf8_string_loclen X<is_utf8_string_loclen>, pv_uni_display +X<pv_uni_display>, sv_cat_decode X<sv_cat_decode>, sv_recode_to_utf8 +X<sv_recode_to_utf8>, sv_uni_display X<sv_uni_display>, to_utf8_case +X<to_utf8_case>, to_utf8_fold X<to_utf8_fold>, to_utf8_lower X<to_utf8_lower>, to_utf8_title X<to_utf8_title>, to_utf8_upper X<to_utf8_upper>, utf8n_to_uvchr X<utf8n_to_uvchr>, utf8n_to_uvuni X<utf8n_to_uvuni>, utf8_distance X<utf8_distance>, utf8_hop X<utf8_hop>, @@ -6144,12 +6309,15 @@ X<uvchr_to_utf8>, uvuni_to_utf8_flags X<uvuni_to_utf8_flags> ax X<ax>, CLASS X<CLASS>, dAX X<dAX>, dAXMARK X<dAXMARK>, dITEMS X<dITEMS>, dUNDERBAR X<dUNDERBAR>, dXSARGS X<dXSARGS>, dXSI32 X<dXSI32>, items X<items>, ix X<ix>, newXSproto X<newXSproto>, RETVAL X<RETVAL>, ST X<ST>, -THIS X<THIS>, UNDERBAR X<UNDERBAR>, XS X<XS>, XS_VERSION X<XS_VERSION>, -XS_VERSION_BOOTCHECK X<XS_VERSION_BOOTCHECK> +THIS X<THIS>, UNDERBAR X<UNDERBAR>, XS X<XS>, XS_APIVERSION_BOOTCHECK +X<XS_APIVERSION_BOOTCHECK>, XS_VERSION X<XS_VERSION>, XS_VERSION_BOOTCHECK +X<XS_VERSION_BOOTCHECK> =item Warning and Dieing -croak X<croak>, warn X<warn> +croak X<croak>, croak_no_modify X<croak_no_modify>, croak_sv X<croak_sv>, +die X<die>, die_sv X<die_sv>, vcroak X<vcroak>, vwarn X<vwarn>, warn +X<warn>, warn_sv X<warn_sv> =item Undocumented functions @@ -6166,21 +6334,23 @@ PerlIO_setlinebuf X<PerlIO_setlinebuf>, PerlIO_stderr X<PerlIO_stderr>, PerlIO_stdin X<PerlIO_stdin>, PerlIO_stdout X<PerlIO_stdout>, PerlIO_tell X<PerlIO_tell>, PerlIO_unread X<PerlIO_unread>, PerlIO_write X<PerlIO_write>, Slab_Alloc X<Slab_Alloc>, Slab_Free X<Slab_Free>, -amagic_call X<amagic_call>, any_dup X<any_dup>, apply_attrs_string +_to_uni_fold_flags X<_to_uni_fold_flags>, _to_utf8_fold_flags +X<_to_utf8_fold_flags>, amagic_call X<amagic_call>, amagic_deref_call +X<amagic_deref_call>, any_dup X<any_dup>, apply_attrs_string X<apply_attrs_string>, atfork_lock X<atfork_lock>, atfork_unlock X<atfork_unlock>, av_arylen_p X<av_arylen_p>, av_iter_p X<av_iter_p>, block_gimme X<block_gimme>, call_atexit X<call_atexit>, call_list X<call_list>, calloc X<calloc>, cast_i32 X<cast_i32>, cast_iv X<cast_iv>, cast_ulong X<cast_ulong>, cast_uv X<cast_uv>, ck_warner X<ck_warner>, ck_warner_d X<ck_warner_d>, ckwarn X<ckwarn>, ckwarn_d X<ckwarn_d>, -croak_nocontext X<croak_nocontext>, csighandler X<csighandler>, -custom_op_desc X<custom_op_desc>, custom_op_name X<custom_op_name>, cx_dump +clone_params_del X<clone_params_del>, clone_params_new X<clone_params_new>, +croak_nocontext X<croak_nocontext>, csighandler X<csighandler>, cx_dump X<cx_dump>, cx_dup X<cx_dup>, cxinc X<cxinc>, deb X<deb>, deb_nocontext X<deb_nocontext>, debop X<debop>, debprofdump X<debprofdump>, debstack X<debstack>, debstackptrs X<debstackptrs>, delimcpy X<delimcpy>, -despatch_signals X<despatch_signals>, die X<die>, die_nocontext -X<die_nocontext>, dirp_dup X<dirp_dup>, do_aspawn X<do_aspawn>, do_binmode -X<do_binmode>, do_close X<do_close>, do_gv_dump X<do_gv_dump>, do_gvgv_dump +despatch_signals X<despatch_signals>, die_nocontext X<die_nocontext>, +dirp_dup X<dirp_dup>, do_aspawn X<do_aspawn>, do_binmode X<do_binmode>, +do_close X<do_close>, do_gv_dump X<do_gv_dump>, do_gvgv_dump X<do_gvgv_dump>, do_hv_dump X<do_hv_dump>, do_join X<do_join>, do_magic_dump X<do_magic_dump>, do_op_dump X<do_op_dump>, do_open X<do_open>, do_open9 X<do_open9>, do_openn X<do_openn>, do_pmop_dump @@ -6192,13 +6362,15 @@ X<dump_fds>, dump_form X<dump_form>, dump_indent X<dump_indent>, dump_mstats X<dump_mstats>, dump_packsubs X<dump_packsubs>, dump_sub X<dump_sub>, dump_vindent X<dump_vindent>, fetch_cop_label X<fetch_cop_label>, filter_add X<filter_add>, filter_del X<filter_del>, -filter_read X<filter_read>, find_rundefsvoffset X<find_rundefsvoffset>, -form_nocontext X<form_nocontext>, fp_dup X<fp_dup>, fprintf_nocontext -X<fprintf_nocontext>, free_global_struct X<free_global_struct>, free_tmps -X<free_tmps>, get_context X<get_context>, get_mstats X<get_mstats>, -get_op_descs X<get_op_descs>, get_op_names X<get_op_names>, get_ppaddr -X<get_ppaddr>, get_vtbl X<get_vtbl>, gp_dup X<gp_dup>, gp_free X<gp_free>, -gp_ref X<gp_ref>, gv_AVadd X<gv_AVadd>, gv_HVadd X<gv_HVadd>, gv_IOadd +filter_read X<filter_read>, find_rundefsv X<find_rundefsv>, +find_rundefsvoffset X<find_rundefsvoffset>, foldEQ_latin1 X<foldEQ_latin1>, +foldEQ_utf8_flags X<foldEQ_utf8_flags>, form_nocontext X<form_nocontext>, +fp_dup X<fp_dup>, fprintf_nocontext X<fprintf_nocontext>, +free_global_struct X<free_global_struct>, free_tmps X<free_tmps>, +get_context X<get_context>, get_mstats X<get_mstats>, get_op_descs +X<get_op_descs>, get_op_names X<get_op_names>, get_ppaddr X<get_ppaddr>, +get_vtbl X<get_vtbl>, gp_dup X<gp_dup>, gp_free X<gp_free>, gp_ref +X<gp_ref>, gv_AVadd X<gv_AVadd>, gv_HVadd X<gv_HVadd>, gv_IOadd X<gv_IOadd>, gv_SVadd X<gv_SVadd>, gv_add_by_type X<gv_add_by_type>, gv_autoload4 X<gv_autoload4>, gv_check X<gv_check>, gv_dump X<gv_dump>, gv_efullname X<gv_efullname>, gv_efullname3 X<gv_efullname3>, gv_efullname4 @@ -6214,36 +6386,36 @@ hv_eiter_set X<hv_eiter_set>, hv_free_ent X<hv_free_ent>, hv_ksplit X<hv_ksplit>, hv_name_set X<hv_name_set>, hv_placeholders_get X<hv_placeholders_get>, hv_placeholders_p X<hv_placeholders_p>, hv_placeholders_set X<hv_placeholders_set>, hv_riter_p X<hv_riter_p>, -hv_riter_set X<hv_riter_set>, hv_store_flags X<hv_store_flags>, ibcmp -X<ibcmp>, ibcmp_locale X<ibcmp_locale>, init_global_struct -X<init_global_struct>, init_i18nl10n X<init_i18nl10n>, init_i18nl14n -X<init_i18nl14n>, init_stacks X<init_stacks>, init_tm X<init_tm>, instr -X<instr>, is_lvalue_sub X<is_lvalue_sub>, is_uni_alnum X<is_uni_alnum>, -is_uni_alnum_lc X<is_uni_alnum_lc>, is_uni_alpha X<is_uni_alpha>, -is_uni_alpha_lc X<is_uni_alpha_lc>, is_uni_ascii X<is_uni_ascii>, -is_uni_ascii_lc X<is_uni_ascii_lc>, is_uni_cntrl X<is_uni_cntrl>, -is_uni_cntrl_lc X<is_uni_cntrl_lc>, is_uni_digit X<is_uni_digit>, -is_uni_digit_lc X<is_uni_digit_lc>, is_uni_graph X<is_uni_graph>, -is_uni_graph_lc X<is_uni_graph_lc>, is_uni_idfirst X<is_uni_idfirst>, -is_uni_idfirst_lc X<is_uni_idfirst_lc>, is_uni_lower X<is_uni_lower>, -is_uni_lower_lc X<is_uni_lower_lc>, is_uni_print X<is_uni_print>, -is_uni_print_lc X<is_uni_print_lc>, is_uni_punct X<is_uni_punct>, -is_uni_punct_lc X<is_uni_punct_lc>, is_uni_space X<is_uni_space>, -is_uni_space_lc X<is_uni_space_lc>, is_uni_upper X<is_uni_upper>, -is_uni_upper_lc X<is_uni_upper_lc>, is_uni_xdigit X<is_uni_xdigit>, -is_uni_xdigit_lc X<is_uni_xdigit_lc>, is_utf8_alnum X<is_utf8_alnum>, -is_utf8_alpha X<is_utf8_alpha>, is_utf8_ascii X<is_utf8_ascii>, -is_utf8_cntrl X<is_utf8_cntrl>, is_utf8_digit X<is_utf8_digit>, -is_utf8_graph X<is_utf8_graph>, is_utf8_idcont X<is_utf8_idcont>, -is_utf8_idfirst X<is_utf8_idfirst>, is_utf8_lower X<is_utf8_lower>, -is_utf8_mark X<is_utf8_mark>, is_utf8_perl_space X<is_utf8_perl_space>, -is_utf8_perl_word X<is_utf8_perl_word>, is_utf8_posix_digit -X<is_utf8_posix_digit>, is_utf8_print X<is_utf8_print>, is_utf8_punct -X<is_utf8_punct>, is_utf8_space X<is_utf8_space>, is_utf8_upper -X<is_utf8_upper>, is_utf8_xdigit X<is_utf8_xdigit>, leave_scope -X<leave_scope>, load_module_nocontext X<load_module_nocontext>, magic_dump -X<magic_dump>, malloc X<malloc>, markstack_grow X<markstack_grow>, mess -X<mess>, mess_nocontext X<mess_nocontext>, mfree X<mfree>, mg_dup +hv_riter_set X<hv_riter_set>, hv_store_flags X<hv_store_flags>, +init_global_struct X<init_global_struct>, init_i18nl10n X<init_i18nl10n>, +init_i18nl14n X<init_i18nl14n>, init_stacks X<init_stacks>, init_tm +X<init_tm>, instr X<instr>, is_lvalue_sub X<is_lvalue_sub>, is_uni_alnum +X<is_uni_alnum>, is_uni_alnum_lc X<is_uni_alnum_lc>, is_uni_alpha +X<is_uni_alpha>, is_uni_alpha_lc X<is_uni_alpha_lc>, is_uni_ascii +X<is_uni_ascii>, is_uni_ascii_lc X<is_uni_ascii_lc>, is_uni_cntrl +X<is_uni_cntrl>, is_uni_cntrl_lc X<is_uni_cntrl_lc>, is_uni_digit +X<is_uni_digit>, is_uni_digit_lc X<is_uni_digit_lc>, is_uni_graph +X<is_uni_graph>, is_uni_graph_lc X<is_uni_graph_lc>, is_uni_idfirst +X<is_uni_idfirst>, is_uni_idfirst_lc X<is_uni_idfirst_lc>, is_uni_lower +X<is_uni_lower>, is_uni_lower_lc X<is_uni_lower_lc>, is_uni_print +X<is_uni_print>, is_uni_print_lc X<is_uni_print_lc>, is_uni_punct +X<is_uni_punct>, is_uni_punct_lc X<is_uni_punct_lc>, is_uni_space +X<is_uni_space>, is_uni_space_lc X<is_uni_space_lc>, is_uni_upper +X<is_uni_upper>, is_uni_upper_lc X<is_uni_upper_lc>, is_uni_xdigit +X<is_uni_xdigit>, is_uni_xdigit_lc X<is_uni_xdigit_lc>, is_utf8_alnum +X<is_utf8_alnum>, is_utf8_alpha X<is_utf8_alpha>, is_utf8_ascii +X<is_utf8_ascii>, is_utf8_cntrl X<is_utf8_cntrl>, is_utf8_digit +X<is_utf8_digit>, is_utf8_graph X<is_utf8_graph>, is_utf8_idcont +X<is_utf8_idcont>, is_utf8_idfirst X<is_utf8_idfirst>, is_utf8_lower +X<is_utf8_lower>, is_utf8_mark X<is_utf8_mark>, is_utf8_perl_space +X<is_utf8_perl_space>, is_utf8_perl_word X<is_utf8_perl_word>, +is_utf8_posix_digit X<is_utf8_posix_digit>, is_utf8_print X<is_utf8_print>, +is_utf8_punct X<is_utf8_punct>, is_utf8_space X<is_utf8_space>, +is_utf8_upper X<is_utf8_upper>, is_utf8_xdigit X<is_utf8_xdigit>, +is_utf8_xidcont X<is_utf8_xidcont>, is_utf8_xidfirst X<is_utf8_xidfirst>, +leave_scope X<leave_scope>, load_module_nocontext X<load_module_nocontext>, +magic_dump X<magic_dump>, malloc X<malloc>, markstack_grow +X<markstack_grow>, mess_nocontext X<mess_nocontext>, mfree X<mfree>, mg_dup X<mg_dup>, mg_size X<mg_size>, mini_mktime X<mini_mktime>, moreswitches X<moreswitches>, mro_get_from_name X<mro_get_from_name>, mro_get_private_data X<mro_get_private_data>, mro_register X<mro_register>, @@ -6259,37 +6431,29 @@ my_setenv X<my_setenv>, my_socketpair X<my_socketpair>, my_stat X<my_stat>, my_strftime X<my_strftime>, my_strlcat X<my_strlcat>, my_strlcpy X<my_strlcpy>, my_swap X<my_swap>, newANONATTRSUB X<newANONATTRSUB>, newANONHASH X<newANONHASH>, newANONLIST X<newANONLIST>, newANONSUB -X<newANONSUB>, newASSIGNOP X<newASSIGNOP>, newATTRSUB X<newATTRSUB>, -newAVREF X<newAVREF>, newBINOP X<newBINOP>, newCONDOP X<newCONDOP>, -newCVREF X<newCVREF>, newFORM X<newFORM>, newFOROP X<newFOROP>, newGIVENOP -X<newGIVENOP>, newGVOP X<newGVOP>, newGVREF X<newGVREF>, newGVgen +X<newANONSUB>, newATTRSUB X<newATTRSUB>, newAVREF X<newAVREF>, newCVREF +X<newCVREF>, newFORM X<newFORM>, newGVREF X<newGVREF>, newGVgen X<newGVgen>, newHVREF X<newHVREF>, newHVhv X<newHVhv>, newIO X<newIO>, -newLISTOP X<newLISTOP>, newLOGOP X<newLOGOP>, newLOOPEX X<newLOOPEX>, -newLOOPOP X<newLOOPOP>, newMYSUB X<newMYSUB>, newNULLLIST X<newNULLLIST>, -newOP X<newOP>, newPADOP X<newPADOP>, newPMOP X<newPMOP>, newPROG -X<newPROG>, newPVOP X<newPVOP>, newRANGE X<newRANGE>, newRV X<newRV>, -newSLICEOP X<newSLICEOP>, newSTATEOP X<newSTATEOP>, newSUB X<newSUB>, -newSVOP X<newSVOP>, newSVREF X<newSVREF>, newSVpvf_nocontext -X<newSVpvf_nocontext>, newUNOP X<newUNOP>, newWHENOP X<newWHENOP>, -newWHILEOP X<newWHILEOP>, newXS_flags X<newXS_flags>, new_collate -X<new_collate>, new_ctype X<new_ctype>, new_numeric X<new_numeric>, -new_stackinfo X<new_stackinfo>, ninstr X<ninstr>, op_dump X<op_dump>, -op_free X<op_free>, op_null X<op_null>, op_refcnt_lock X<op_refcnt_lock>, -op_refcnt_unlock X<op_refcnt_unlock>, parser_dup X<parser_dup>, -perl_alloc_using X<perl_alloc_using>, perl_clone_using X<perl_clone_using>, -pmop_dump X<pmop_dump>, pop_scope X<pop_scope>, pregcomp X<pregcomp>, -pregexec X<pregexec>, pregfree X<pregfree>, pregfree2 X<pregfree2>, -printf_nocontext X<printf_nocontext>, ptr_table_clear X<ptr_table_clear>, -ptr_table_fetch X<ptr_table_fetch>, ptr_table_free X<ptr_table_free>, -ptr_table_new X<ptr_table_new>, ptr_table_split X<ptr_table_split>, -ptr_table_store X<ptr_table_store>, push_scope X<push_scope>, re_compile -X<re_compile>, re_dup_guts X<re_dup_guts>, re_intuit_start -X<re_intuit_start>, re_intuit_string X<re_intuit_string>, realloc -X<realloc>, reentrant_free X<reentrant_free>, reentrant_init -X<reentrant_init>, reentrant_retry X<reentrant_retry>, reentrant_size -X<reentrant_size>, ref X<ref>, reg_named_buff_all X<reg_named_buff_all>, -reg_named_buff_exists X<reg_named_buff_exists>, reg_named_buff_fetch -X<reg_named_buff_fetch>, reg_named_buff_firstkey +newMYSUB X<newMYSUB>, newPROG X<newPROG>, newRV X<newRV>, newSUB X<newSUB>, +newSVREF X<newSVREF>, newSVpvf_nocontext X<newSVpvf_nocontext>, newXS_flags +X<newXS_flags>, new_collate X<new_collate>, new_ctype X<new_ctype>, +new_numeric X<new_numeric>, new_stackinfo X<new_stackinfo>, ninstr +X<ninstr>, op_dump X<op_dump>, op_free X<op_free>, op_null X<op_null>, +op_refcnt_lock X<op_refcnt_lock>, op_refcnt_unlock X<op_refcnt_unlock>, +parser_dup X<parser_dup>, perl_alloc_using X<perl_alloc_using>, +perl_clone_using X<perl_clone_using>, pmop_dump X<pmop_dump>, pop_scope +X<pop_scope>, pregcomp X<pregcomp>, pregexec X<pregexec>, pregfree +X<pregfree>, pregfree2 X<pregfree2>, printf_nocontext X<printf_nocontext>, +ptr_table_clear X<ptr_table_clear>, ptr_table_fetch X<ptr_table_fetch>, +ptr_table_free X<ptr_table_free>, ptr_table_new X<ptr_table_new>, +ptr_table_split X<ptr_table_split>, ptr_table_store X<ptr_table_store>, +push_scope X<push_scope>, re_compile X<re_compile>, re_dup_guts +X<re_dup_guts>, re_intuit_start X<re_intuit_start>, re_intuit_string +X<re_intuit_string>, realloc X<realloc>, reentrant_free X<reentrant_free>, +reentrant_init X<reentrant_init>, reentrant_retry X<reentrant_retry>, +reentrant_size X<reentrant_size>, ref X<ref>, reg_named_buff_all +X<reg_named_buff_all>, reg_named_buff_exists X<reg_named_buff_exists>, +reg_named_buff_fetch X<reg_named_buff_fetch>, reg_named_buff_firstkey X<reg_named_buff_firstkey>, reg_named_buff_nextkey X<reg_named_buff_nextkey>, reg_named_buff_scalar X<reg_named_buff_scalar>, regclass_swash X<regclass_swash>, regdump X<regdump>, regdupe_internal @@ -6305,15 +6469,17 @@ save_aelem X<save_aelem>, save_aelem_flags X<save_aelem_flags>, save_alloc X<save_alloc>, save_aptr X<save_aptr>, save_ary X<save_ary>, save_bool X<save_bool>, save_clearsv X<save_clearsv>, save_delete X<save_delete>, save_destructor X<save_destructor>, save_destructor_x X<save_destructor_x>, -save_freepv X<save_freepv>, save_freesv X<save_freesv>, save_generic_pvref -X<save_generic_pvref>, save_generic_svref X<save_generic_svref>, save_gp -X<save_gp>, save_hash X<save_hash>, save_hdelete X<save_hdelete>, -save_helem X<save_helem>, save_helem_flags X<save_helem_flags>, save_hptr +save_freeop X<save_freeop>, save_freepv X<save_freepv>, save_freesv +X<save_freesv>, save_generic_pvref X<save_generic_pvref>, +save_generic_svref X<save_generic_svref>, save_gp X<save_gp>, save_hash +X<save_hash>, save_hdelete X<save_hdelete>, save_helem X<save_helem>, +save_helem_flags X<save_helem_flags>, save_hints X<save_hints>, save_hptr X<save_hptr>, save_int X<save_int>, save_item X<save_item>, save_iv X<save_iv>, save_list X<save_list>, save_long X<save_long>, -save_mortalizesv X<save_mortalizesv>, save_nogv X<save_nogv>, -save_padsv_and_mortalize X<save_padsv_and_mortalize>, save_pptr -X<save_pptr>, save_pushptr X<save_pushptr>, save_re_context +save_mortalizesv X<save_mortalizesv>, save_nogv X<save_nogv>, save_op +X<save_op>, save_padsv_and_mortalize X<save_padsv_and_mortalize>, save_pptr +X<save_pptr>, save_pushi32ptr X<save_pushi32ptr>, save_pushptr +X<save_pushptr>, save_pushptrptr X<save_pushptrptr>, save_re_context X<save_re_context>, save_scalar X<save_scalar>, save_set_svflags X<save_set_svflags>, save_shared_pvref X<save_shared_pvref>, save_sptr X<save_sptr>, save_svref X<save_svref>, save_vptr X<save_vptr>, @@ -6328,24 +6494,23 @@ X<stashpv_hvname_match>, str_to_version X<str_to_version>, sv_2iv X<sv_2iv>, sv_2pv X<sv_2pv>, sv_2uv X<sv_2uv>, sv_catpvf_mg_nocontext X<sv_catpvf_mg_nocontext>, sv_catpvf_nocontext X<sv_catpvf_nocontext>, sv_compile_2op X<sv_compile_2op>, sv_dump X<sv_dump>, sv_dup X<sv_dup>, -sv_peek X<sv_peek>, sv_pvn_nomg X<sv_pvn_nomg>, sv_setpvf_mg_nocontext -X<sv_setpvf_mg_nocontext>, sv_setpvf_nocontext X<sv_setpvf_nocontext>, -sv_utf8_upgrade_flags_grow X<sv_utf8_upgrade_flags_grow>, swash_fetch -X<swash_fetch>, swash_init X<swash_init>, sys_init X<sys_init>, sys_init3 -X<sys_init3>, sys_intern_clear X<sys_intern_clear>, sys_intern_dup -X<sys_intern_dup>, sys_intern_init X<sys_intern_init>, sys_term -X<sys_term>, taint_env X<taint_env>, taint_proper X<taint_proper>, -tmps_grow X<tmps_grow>, to_uni_fold X<to_uni_fold>, to_uni_lower -X<to_uni_lower>, to_uni_lower_lc X<to_uni_lower_lc>, to_uni_title -X<to_uni_title>, to_uni_title_lc X<to_uni_title_lc>, to_uni_upper -X<to_uni_upper>, to_uni_upper_lc X<to_uni_upper_lc>, unlnk X<unlnk>, -unsharepvn X<unsharepvn>, utf16_to_utf8 X<utf16_to_utf8>, -utf16_to_utf8_reversed X<utf16_to_utf8_reversed>, uvchr_to_utf8_flags -X<uvchr_to_utf8_flags>, uvuni_to_utf8 X<uvuni_to_utf8>, vcroak X<vcroak>, -vdeb X<vdeb>, vform X<vform>, vload_module X<vload_module>, vmess X<vmess>, -vnewSVpvf X<vnewSVpvf>, vwarn X<vwarn>, vwarner X<vwarner>, warn_nocontext -X<warn_nocontext>, warner X<warner>, warner_nocontext X<warner_nocontext>, -whichsig X<whichsig> +sv_dup_inc X<sv_dup_inc>, sv_peek X<sv_peek>, sv_pvn_nomg X<sv_pvn_nomg>, +sv_setpvf_mg_nocontext X<sv_setpvf_mg_nocontext>, sv_setpvf_nocontext +X<sv_setpvf_nocontext>, sv_utf8_upgrade_flags_grow +X<sv_utf8_upgrade_flags_grow>, swash_fetch X<swash_fetch>, swash_init +X<swash_init>, sys_init X<sys_init>, sys_init3 X<sys_init3>, +sys_intern_clear X<sys_intern_clear>, sys_intern_dup X<sys_intern_dup>, +sys_intern_init X<sys_intern_init>, sys_term X<sys_term>, taint_env +X<taint_env>, taint_proper X<taint_proper>, tmps_grow X<tmps_grow>, +to_uni_fold X<to_uni_fold>, to_uni_lower X<to_uni_lower>, to_uni_lower_lc +X<to_uni_lower_lc>, to_uni_title X<to_uni_title>, to_uni_title_lc +X<to_uni_title_lc>, to_uni_upper X<to_uni_upper>, to_uni_upper_lc +X<to_uni_upper_lc>, unlnk X<unlnk>, unsharepvn X<unsharepvn>, utf16_to_utf8 +X<utf16_to_utf8>, utf16_to_utf8_reversed X<utf16_to_utf8_reversed>, +uvchr_to_utf8_flags X<uvchr_to_utf8_flags>, uvuni_to_utf8 X<uvuni_to_utf8>, +vdeb X<vdeb>, vform X<vform>, vload_module X<vload_module>, vnewSVpvf +X<vnewSVpvf>, vwarner X<vwarner>, warn_nocontext X<warn_nocontext>, warner +X<warner>, warner_nocontext X<warner_nocontext>, whichsig X<whichsig> =item AUTHORS @@ -6361,10 +6526,26 @@ whichsig X<whichsig> =item DESCRIPTION X<internal Perl functions> X<interpreter functions> +=item Compile-time scope hooks + +BhkENTRY X<BhkENTRY>, BhkFLAGS X<BhkFLAGS>, CALL_BLOCK_HOOKS +X<CALL_BLOCK_HOOKS> + =item CV reference counts and CvOUTSIDE CvWEAKOUTSIDE X<CvWEAKOUTSIDE> +=item Embedding Functions + +cv_clone X<cv_clone>, cv_dump X<cv_dump>, do_dump_pad X<do_dump_pad>, +intro_my X<intro_my>, pad_add_anon X<pad_add_anon>, pad_add_name +X<pad_add_name>, pad_alloc X<pad_alloc>, pad_block_start +X<pad_block_start>, pad_check_dup X<pad_check_dup>, pad_findlex +X<pad_findlex>, pad_fixup_inner_anons X<pad_fixup_inner_anons>, pad_free +X<pad_free>, pad_leavemy X<pad_leavemy>, pad_push X<pad_push>, pad_reset +X<pad_reset>, pad_setsv X<pad_setsv>, pad_swipe X<pad_swipe>, pad_tidy +X<pad_tidy> + =item Functions in file pad.h CX_CURPAD_SAVE X<CX_CURPAD_SAVE>, CX_CURPAD_SV X<CX_CURPAD_SV>, PAD_BASE_SV @@ -6389,8 +6570,16 @@ gv_try_downgrade X<gv_try_downgrade>, is_gv_magical_sv X<is_gv_magical_sv> =item Hash Manipulation Functions -refcounted_he_chain_2hv X<refcounted_he_chain_2hv>, refcounted_he_free -X<refcounted_he_free>, refcounted_he_new X<refcounted_he_new> +hv_ename_add X<hv_ename_add>, hv_ename_delete X<hv_ename_delete>, +refcounted_he_chain_2hv X<refcounted_he_chain_2hv>, refcounted_he_fetch_pv +X<refcounted_he_fetch_pv>, refcounted_he_fetch_pvn +X<refcounted_he_fetch_pvn>, refcounted_he_fetch_pvs +X<refcounted_he_fetch_pvs>, refcounted_he_fetch_sv +X<refcounted_he_fetch_sv>, refcounted_he_free X<refcounted_he_free>, +refcounted_he_inc X<refcounted_he_inc>, refcounted_he_new_pv +X<refcounted_he_new_pv>, refcounted_he_new_pvn X<refcounted_he_new_pvn>, +refcounted_he_new_pvs X<refcounted_he_new_pvs>, refcounted_he_new_sv +X<refcounted_he_new_sv> =item IO Functions @@ -6399,23 +6588,17 @@ start_glob X<start_glob> =item Magical Functions magic_clearhint X<magic_clearhint>, magic_clearhints X<magic_clearhints>, -magic_sethint X<magic_sethint>, mg_localize X<mg_localize> +magic_methcall X<magic_methcall>, magic_sethint X<magic_sethint>, +mg_localize X<mg_localize> =item MRO Functions mro_get_linear_isa_dfs X<mro_get_linear_isa_dfs>, mro_isa_changed_in -X<mro_isa_changed_in> +X<mro_isa_changed_in>, mro_package_moved X<mro_package_moved> =item Pad Data Structures -CvPADLIST X<CvPADLIST>, cv_clone X<cv_clone>, cv_dump X<cv_dump>, -do_dump_pad X<do_dump_pad>, intro_my X<intro_my>, pad_add_anon -X<pad_add_anon>, pad_add_name X<pad_add_name>, pad_alloc X<pad_alloc>, -pad_block_start X<pad_block_start>, pad_check_dup X<pad_check_dup>, -pad_findlex X<pad_findlex>, pad_fixup_inner_anons X<pad_fixup_inner_anons>, -pad_free X<pad_free>, pad_leavemy X<pad_leavemy>, pad_new X<pad_new>, -pad_push X<pad_push>, pad_reset X<pad_reset>, pad_setsv X<pad_setsv>, -pad_swipe X<pad_swipe>, pad_tidy X<pad_tidy>, pad_undef X<pad_undef> +CvPADLIST X<CvPADLIST>, pad_new X<pad_new> =item Per-Interpreter Variables @@ -6442,59 +6625,51 @@ find_uninit_var X<find_uninit_var>, report_uninit X<report_uninit> =item Undocumented functions -F0convert X<F0convert>, Slab_to_rw X<Slab_to_rw>, add_data X<add_data>, -add_utf16_textfilter X<add_utf16_textfilter>, addmad X<addmad>, allocmy -X<allocmy>, amagic_cmp X<amagic_cmp>, amagic_cmp_locale -X<amagic_cmp_locale>, amagic_i_ncmp X<amagic_i_ncmp>, amagic_ncmp -X<amagic_ncmp>, anonymise_cv X<anonymise_cv>, ao X<ao>, append_elem -X<append_elem>, append_list X<append_list>, append_madprops -X<append_madprops>, apply X<apply>, apply_attrs X<apply_attrs>, -apply_attrs_my X<apply_attrs_my>, av_reify X<av_reify>, bad_type -X<bad_type>, bind_match X<bind_match>, block_end X<block_end>, block_start -X<block_start>, boot_core_PerlIO X<boot_core_PerlIO>, boot_core_UNIVERSAL -X<boot_core_UNIVERSAL>, boot_core_mro X<boot_core_mro>, bytes_to_uni -X<bytes_to_uni>, cando X<cando>, check_type_and_open -X<check_type_and_open>, check_uni X<check_uni>, checkcomma X<checkcomma>, -checkposixcc X<checkposixcc>, ck_anoncode X<ck_anoncode>, ck_bitop -X<ck_bitop>, ck_concat X<ck_concat>, ck_defined X<ck_defined>, ck_delete -X<ck_delete>, ck_die X<ck_die>, ck_each X<ck_each>, ck_eof X<ck_eof>, -ck_eval X<ck_eval>, ck_exec X<ck_exec>, ck_exists X<ck_exists>, ck_exit -X<ck_exit>, ck_ftst X<ck_ftst>, ck_fun X<ck_fun>, ck_glob X<ck_glob>, -ck_grep X<ck_grep>, ck_index X<ck_index>, ck_join X<ck_join>, ck_lfun -X<ck_lfun>, ck_listiob X<ck_listiob>, ck_match X<ck_match>, ck_method -X<ck_method>, ck_null X<ck_null>, ck_open X<ck_open>, ck_readline -X<ck_readline>, ck_repeat X<ck_repeat>, ck_require X<ck_require>, ck_return -X<ck_return>, ck_rfun X<ck_rfun>, ck_rvconst X<ck_rvconst>, ck_sassign -X<ck_sassign>, ck_select X<ck_select>, ck_shift X<ck_shift>, ck_sort -X<ck_sort>, ck_spair X<ck_spair>, ck_split X<ck_split>, ck_subr X<ck_subr>, -ck_substr X<ck_substr>, ck_svconst X<ck_svconst>, ck_trunc X<ck_trunc>, -ck_unpack X<ck_unpack>, ckwarn_common X<ckwarn_common>, cl_and X<cl_and>, -cl_anything X<cl_anything>, cl_init X<cl_init>, cl_init_zero -X<cl_init_zero>, cl_is_anything X<cl_is_anything>, cl_or X<cl_or>, +F0convert X<F0convert>, Slab_to_rw X<Slab_to_rw>, _append_range_to_invlist +X<_append_range_to_invlist>, _new_invlist X<_new_invlist>, +_swash_inversion_hash X<_swash_inversion_hash>, _swash_to_invlist +X<_swash_to_invlist>, add_alternate X<add_alternate>, add_cp_to_invlist +X<add_cp_to_invlist>, add_data X<add_data>, add_range_to_invlist +X<add_range_to_invlist>, add_utf16_textfilter X<add_utf16_textfilter>, +addmad X<addmad>, allocmy X<allocmy>, amagic_cmp X<amagic_cmp>, +amagic_cmp_locale X<amagic_cmp_locale>, amagic_i_ncmp X<amagic_i_ncmp>, +amagic_ncmp X<amagic_ncmp>, anonymise_cv_maybe X<anonymise_cv_maybe>, ao +X<ao>, append_madprops X<append_madprops>, apply X<apply>, apply_attrs +X<apply_attrs>, apply_attrs_my X<apply_attrs_my>, +assert_uft8_cache_coherent X<assert_uft8_cache_coherent>, av_reify +X<av_reify>, bad_type X<bad_type>, bind_match X<bind_match>, block_end +X<block_end>, block_start X<block_start>, boot_core_PerlIO +X<boot_core_PerlIO>, boot_core_UNIVERSAL X<boot_core_UNIVERSAL>, +boot_core_mro X<boot_core_mro>, bytes_to_uni X<bytes_to_uni>, cando +X<cando>, check_type_and_open X<check_type_and_open>, check_uni +X<check_uni>, check_utf8_print X<check_utf8_print>, checkcomma +X<checkcomma>, checkposixcc X<checkposixcc>, ckwarn_common +X<ckwarn_common>, cl_and X<cl_and>, cl_anything X<cl_anything>, cl_init +X<cl_init>, cl_is_anything X<cl_is_anything>, cl_or X<cl_or>, clear_placeholders X<clear_placeholders>, closest_cop X<closest_cop>, convert X<convert>, cop_free X<cop_free>, cr_textfilter X<cr_textfilter>, -create_eval_scope X<create_eval_scope>, curmad X<curmad>, cv_ckproto_len -X<cv_ckproto_len>, deb_curcv X<deb_curcv>, deb_stack_all X<deb_stack_all>, +create_eval_scope X<create_eval_scope>, curmad X<curmad>, curse X<curse>, +cv_ckproto_len X<cv_ckproto_len>, cvgv_set X<cvgv_set>, cvstash_set +X<cvstash_set>, deb_curcv X<deb_curcv>, deb_stack_all X<deb_stack_all>, deb_stack_n X<deb_stack_n>, debprof X<debprof>, debug_start_match X<debug_start_match>, del_sv X<del_sv>, delete_eval_scope X<delete_eval_scope>, deprecate_commaless_var_list X<deprecate_commaless_var_list>, destroy_matcher X<destroy_matcher>, -die_where X<die_where>, div128 X<div128>, do_aexec X<do_aexec>, do_aexec5 -X<do_aexec5>, do_chomp X<do_chomp>, do_chop X<do_chop>, do_delete_local -X<do_delete_local>, do_eof X<do_eof>, do_exec X<do_exec>, do_exec3 -X<do_exec3>, do_execfree X<do_execfree>, do_ipcctl X<do_ipcctl>, do_ipcget -X<do_ipcget>, do_kv X<do_kv>, do_msgrcv X<do_msgrcv>, do_msgsnd -X<do_msgsnd>, do_oddball X<do_oddball>, do_op_xmldump X<do_op_xmldump>, -do_pmop_xmldump X<do_pmop_xmldump>, do_print X<do_print>, do_readline -X<do_readline>, do_seek X<do_seek>, do_semop X<do_semop>, do_shmio -X<do_shmio>, do_smartmatch X<do_smartmatch>, do_sysseek X<do_sysseek>, -do_tell X<do_tell>, do_trans X<do_trans>, do_trans_complex -X<do_trans_complex>, do_trans_complex_utf8 X<do_trans_complex_utf8>, -do_trans_count X<do_trans_count>, do_trans_count_utf8 -X<do_trans_count_utf8>, do_trans_simple X<do_trans_simple>, -do_trans_simple_utf8 X<do_trans_simple_utf8>, do_vecget X<do_vecget>, -do_vecset X<do_vecset>, do_vop X<do_vop>, doeval X<doeval>, dofile -X<dofile>, dofindlabel X<dofindlabel>, doform X<doform>, dooneliner +die_unwind X<die_unwind>, div128 X<div128>, do_aexec X<do_aexec>, do_aexec5 +X<do_aexec5>, do_chomp X<do_chomp>, do_delete_local X<do_delete_local>, +do_eof X<do_eof>, do_exec X<do_exec>, do_exec3 X<do_exec3>, do_execfree +X<do_execfree>, do_ipcctl X<do_ipcctl>, do_ipcget X<do_ipcget>, do_msgrcv +X<do_msgrcv>, do_msgsnd X<do_msgsnd>, do_oddball X<do_oddball>, +do_op_xmldump X<do_op_xmldump>, do_pmop_xmldump X<do_pmop_xmldump>, +do_print X<do_print>, do_readline X<do_readline>, do_seek X<do_seek>, +do_semop X<do_semop>, do_shmio X<do_shmio>, do_smartmatch X<do_smartmatch>, +do_sysseek X<do_sysseek>, do_tell X<do_tell>, do_trans X<do_trans>, +do_trans_complex X<do_trans_complex>, do_trans_complex_utf8 +X<do_trans_complex_utf8>, do_trans_count X<do_trans_count>, +do_trans_count_utf8 X<do_trans_count_utf8>, do_trans_simple +X<do_trans_simple>, do_trans_simple_utf8 X<do_trans_simple_utf8>, do_vecget +X<do_vecget>, do_vecset X<do_vecset>, do_vop X<do_vop>, doeval X<doeval>, +dofile X<dofile>, dofindlabel X<dofindlabel>, doform X<doform>, dooneliner X<dooneliner>, doopen_pm X<doopen_pm>, doparseform X<doparseform>, dopoptoeval X<dopoptoeval>, dopoptogiven X<dopoptogiven>, dopoptolabel X<dopoptolabel>, dopoptoloop X<dopoptoloop>, dopoptosub_at @@ -6516,119 +6691,126 @@ X<forbid_setid>, force_ident X<force_ident>, force_list X<force_list>, force_next X<force_next>, force_strict_version X<force_strict_version>, force_version X<force_version>, force_word X<force_word>, forget_pmop X<forget_pmop>, free_tied_hv_pool X<free_tied_hv_pool>, gen_constant_list -X<gen_constant_list>, get_arena X<get_arena>, get_aux_mg X<get_aux_mg>, -get_db_sub X<get_db_sub>, get_debug_opts X<get_debug_opts>, get_hash_seed -X<get_hash_seed>, get_isa_hash X<get_isa_hash>, get_no_modify -X<get_no_modify>, get_num X<get_num>, get_opargs X<get_opargs>, get_re_arg -X<get_re_arg>, getenv_len X<getenv_len>, glob_2number X<glob_2number>, -glob_assign_glob X<glob_assign_glob>, glob_assign_ref X<glob_assign_ref>, -group_end X<group_end>, gv_ename X<gv_ename>, gv_get_super_pkg -X<gv_get_super_pkg>, gv_init_sv X<gv_init_sv>, hfreeentries +X<gen_constant_list>, get_aux_mg X<get_aux_mg>, get_db_sub X<get_db_sub>, +get_debug_opts X<get_debug_opts>, get_hash_seed X<get_hash_seed>, +get_no_modify X<get_no_modify>, get_num X<get_num>, get_opargs +X<get_opargs>, get_re_arg X<get_re_arg>, getenv_len X<getenv_len>, +glob_2number X<glob_2number>, glob_assign_glob X<glob_assign_glob>, +glob_assign_ref X<glob_assign_ref>, grok_bslash_c X<grok_bslash_c>, +grok_bslash_o X<grok_bslash_o>, group_end X<group_end>, gv_ename +X<gv_ename>, gv_get_super_pkg X<gv_get_super_pkg>, gv_init_sv +X<gv_init_sv>, gv_magicalize_isa X<gv_magicalize_isa>, +gv_magicalize_overload X<gv_magicalize_overload>, hfreeentries X<hfreeentries>, hsplit X<hsplit>, hv_auxinit X<hv_auxinit>, -hv_backreferences_p X<hv_backreferences_p>, hv_copy_hints_hv -X<hv_copy_hints_hv>, hv_delete_common X<hv_delete_common>, hv_kill_backrefs -X<hv_kill_backrefs>, hv_magic_check X<hv_magic_check>, hv_notallowed -X<hv_notallowed>, incline X<incline>, incpush X<incpush>, incpush_if_exists -X<incpush_if_exists>, incpush_use_sep X<incpush_use_sep>, ingroup -X<ingroup>, init_argv_symbols X<init_argv_symbols>, init_dbargs +hv_backreferences_p X<hv_backreferences_p>, hv_delete_common +X<hv_delete_common>, hv_kill_backrefs X<hv_kill_backrefs>, hv_magic_check +X<hv_magic_check>, hv_notallowed X<hv_notallowed>, hv_undef_flags +X<hv_undef_flags>, incline X<incline>, incpush X<incpush>, +incpush_if_exists X<incpush_if_exists>, incpush_use_sep X<incpush_use_sep>, +ingroup X<ingroup>, init_argv_symbols X<init_argv_symbols>, init_dbargs X<init_dbargs>, init_debugger X<init_debugger>, init_ids X<init_ids>, init_interp X<init_interp>, init_main_stash X<init_main_stash>, init_perllib X<init_perllib>, init_postdump_symbols X<init_postdump_symbols>, init_predump_symbols X<init_predump_symbols>, intuit_method X<intuit_method>, intuit_more X<intuit_more>, invert -X<invert>, io_close X<io_close>, is_an_int X<is_an_int>, -is_handle_constructor X<is_handle_constructor>, is_inplace_av -X<is_inplace_av>, is_list_assignment X<is_list_assignment>, is_utf8_X_L -X<is_utf8_X_L>, is_utf8_X_LV X<is_utf8_X_LV>, is_utf8_X_LVT -X<is_utf8_X_LVT>, is_utf8_X_LV_LVT_V X<is_utf8_X_LV_LVT_V>, is_utf8_X_T -X<is_utf8_X_T>, is_utf8_X_V X<is_utf8_X_V>, is_utf8_X_begin -X<is_utf8_X_begin>, is_utf8_X_extend X<is_utf8_X_extend>, -is_utf8_X_non_hangul X<is_utf8_X_non_hangul>, is_utf8_X_prepend -X<is_utf8_X_prepend>, is_utf8_char_slow X<is_utf8_char_slow>, -is_utf8_common X<is_utf8_common>, isa_lookup X<isa_lookup>, jmaybe -X<jmaybe>, join_exact X<join_exact>, keyword X<keyword>, -keyword_plugin_standard X<keyword_plugin_standard>, lex_end X<lex_end>, -lex_start X<lex_start>, linklist X<linklist>, list X<list>, listkids -X<listkids>, localize X<localize>, looks_like_bool X<looks_like_bool>, lop -X<lop>, mad_free X<mad_free>, madlex X<madlex>, madparse X<madparse>, -magic_clear_all_env X<magic_clear_all_env>, magic_clearenv -X<magic_clearenv>, magic_clearisa X<magic_clearisa>, magic_clearpack -X<magic_clearpack>, magic_clearsig X<magic_clearsig>, magic_existspack -X<magic_existspack>, magic_freearylen_p X<magic_freearylen_p>, -magic_freeovrld X<magic_freeovrld>, magic_get X<magic_get>, magic_getarylen -X<magic_getarylen>, magic_getdefelem X<magic_getdefelem>, magic_getnkeys -X<magic_getnkeys>, magic_getpack X<magic_getpack>, magic_getpos -X<magic_getpos>, magic_getsig X<magic_getsig>, magic_getsubstr -X<magic_getsubstr>, magic_gettaint X<magic_gettaint>, magic_getuvar -X<magic_getuvar>, magic_getvec X<magic_getvec>, magic_killbackrefs -X<magic_killbackrefs>, magic_len X<magic_len>, magic_methcall -X<magic_methcall>, magic_methpack X<magic_methpack>, magic_nextpack -X<magic_nextpack>, magic_regdata_cnt X<magic_regdata_cnt>, -magic_regdatum_get X<magic_regdatum_get>, magic_regdatum_set -X<magic_regdatum_set>, magic_scalarpack X<magic_scalarpack>, magic_set -X<magic_set>, magic_set_all_env X<magic_set_all_env>, magic_setamagic -X<magic_setamagic>, magic_setarylen X<magic_setarylen>, magic_setcollxfrm -X<magic_setcollxfrm>, magic_setdbline X<magic_setdbline>, magic_setdefelem -X<magic_setdefelem>, magic_setenv X<magic_setenv>, magic_setisa -X<magic_setisa>, magic_setmglob X<magic_setmglob>, magic_setnkeys -X<magic_setnkeys>, magic_setpack X<magic_setpack>, magic_setpos -X<magic_setpos>, magic_setregexp X<magic_setregexp>, magic_setsig -X<magic_setsig>, magic_setsubstr X<magic_setsubstr>, magic_settaint -X<magic_settaint>, magic_setutf8 X<magic_setutf8>, magic_setuvar -X<magic_setuvar>, magic_setvec X<magic_setvec>, magic_sizepack -X<magic_sizepack>, magic_wipepack X<magic_wipepack>, make_matcher -X<make_matcher>, make_trie X<make_trie>, make_trie_failtable -X<make_trie_failtable>, malloc_good_size X<malloc_good_size>, malloced_size -X<malloced_size>, matcher_matches_sv X<matcher_matches_sv>, measure_struct -X<measure_struct>, mem_collxfrm X<mem_collxfrm>, mem_log_common -X<mem_log_common>, mess_alloc X<mess_alloc>, method_common -X<method_common>, missingterm X<missingterm>, mod X<mod>, -mode_from_discipline X<mode_from_discipline>, modkids X<modkids>, -more_bodies X<more_bodies>, more_sv X<more_sv>, mro_meta_dup -X<mro_meta_dup>, mro_meta_init X<mro_meta_init>, mul128 X<mul128>, mulexp10 -X<mulexp10>, my_attrs X<my_attrs>, my_betoh16 X<my_betoh16>, my_betoh32 -X<my_betoh32>, my_betoh64 X<my_betoh64>, my_betohi X<my_betohi>, my_betohl -X<my_betohl>, my_betohs X<my_betohs>, my_clearenv X<my_clearenv>, -my_exit_jump X<my_exit_jump>, my_htobe16 X<my_htobe16>, my_htobe32 -X<my_htobe32>, my_htobe64 X<my_htobe64>, my_htobei X<my_htobei>, my_htobel -X<my_htobel>, my_htobes X<my_htobes>, my_htole16 X<my_htole16>, my_htole32 -X<my_htole32>, my_htole64 X<my_htole64>, my_htolei X<my_htolei>, my_htolel -X<my_htolel>, my_htoles X<my_htoles>, my_kid X<my_kid>, my_letoh16 -X<my_letoh16>, my_letoh32 X<my_letoh32>, my_letoh64 X<my_letoh64>, -my_letohi X<my_letohi>, my_letohl X<my_letohl>, my_letohs X<my_letohs>, -my_swabn X<my_swabn>, my_unexec X<my_unexec>, need_utf8 X<need_utf8>, -newDEFSVOP X<newDEFSVOP>, newGIVWHENOP X<newGIVWHENOP>, newGP X<newGP>, -newMADPROP X<newMADPROP>, newMADsv X<newMADsv>, newTOKEN X<newTOKEN>, -new_constant X<new_constant>, new_he X<new_he>, new_logop X<new_logop>, -new_warnings_bitfield X<new_warnings_bitfield>, next_symbol X<next_symbol>, -nextargv X<nextargv>, nextchar X<nextchar>, no_bareword_allowed -X<no_bareword_allowed>, no_fh_allowed X<no_fh_allowed>, no_op X<no_op>, -not_a_number X<not_a_number>, nuke_stacks X<nuke_stacks>, num_overflow -X<num_overflow>, offer_nice_chunk X<offer_nice_chunk>, oopsAV X<oopsAV>, -oopsHV X<oopsHV>, op_clear X<op_clear>, op_const_sv X<op_const_sv>, -op_getmad X<op_getmad>, op_getmad_weak X<op_getmad_weak>, op_refcnt_dec -X<op_refcnt_dec>, op_refcnt_inc X<op_refcnt_inc>, op_xmldump X<op_xmldump>, -open_script X<open_script>, opt_scalarhv X<opt_scalarhv>, pack_rec -X<pack_rec>, package X<package>, package_version X<package_version>, -pad_add_name_sv X<pad_add_name_sv>, pad_compname_type X<pad_compname_type>, -pad_peg X<pad_peg>, parse_body X<parse_body>, parse_unicode_opts -X<parse_unicode_opts>, parser_free X<parser_free>, path_is_absolute -X<path_is_absolute>, peep X<peep>, pending_Slabs_to_ro -X<pending_Slabs_to_ro>, pidgone X<pidgone>, pm_description -X<pm_description>, pmflag X<pmflag>, pmop_xmldump X<pmop_xmldump>, -pmruntime X<pmruntime>, pmtrans X<pmtrans>, prepend_elem X<prepend_elem>, +X<invert>, invlist_array X<invlist_array>, invlist_destroy +X<invlist_destroy>, invlist_extend X<invlist_extend>, invlist_intersection +X<invlist_intersection>, invlist_len X<invlist_len>, invlist_max +X<invlist_max>, invlist_set_len X<invlist_set_len>, invlist_set_max +X<invlist_set_max>, invlist_trim X<invlist_trim>, invlist_union +X<invlist_union>, invoke_exception_hook X<invoke_exception_hook>, io_close +X<io_close>, is_an_int X<is_an_int>, is_handle_constructor +X<is_handle_constructor>, is_inplace_av X<is_inplace_av>, +is_list_assignment X<is_list_assignment>, is_utf8_X_L X<is_utf8_X_L>, +is_utf8_X_LV X<is_utf8_X_LV>, is_utf8_X_LVT X<is_utf8_X_LVT>, +is_utf8_X_LV_LVT_V X<is_utf8_X_LV_LVT_V>, is_utf8_X_T X<is_utf8_X_T>, +is_utf8_X_V X<is_utf8_X_V>, is_utf8_X_begin X<is_utf8_X_begin>, +is_utf8_X_extend X<is_utf8_X_extend>, is_utf8_X_non_hangul +X<is_utf8_X_non_hangul>, is_utf8_X_prepend X<is_utf8_X_prepend>, +is_utf8_char_slow X<is_utf8_char_slow>, is_utf8_common X<is_utf8_common>, +isa_lookup X<isa_lookup>, jmaybe X<jmaybe>, join_exact X<join_exact>, +keyword X<keyword>, keyword_plugin_standard X<keyword_plugin_standard>, +list X<list>, listkids X<listkids>, localize X<localize>, looks_like_bool +X<looks_like_bool>, lop X<lop>, mad_free X<mad_free>, madlex X<madlex>, +madparse X<madparse>, magic_clear_all_env X<magic_clear_all_env>, +magic_clearenv X<magic_clearenv>, magic_clearisa X<magic_clearisa>, +magic_clearpack X<magic_clearpack>, magic_clearsig X<magic_clearsig>, +magic_existspack X<magic_existspack>, magic_freearylen_p +X<magic_freearylen_p>, magic_freeovrld X<magic_freeovrld>, magic_get +X<magic_get>, magic_getarylen X<magic_getarylen>, magic_getdefelem +X<magic_getdefelem>, magic_getnkeys X<magic_getnkeys>, magic_getpack +X<magic_getpack>, magic_getpos X<magic_getpos>, magic_getsig +X<magic_getsig>, magic_getsubstr X<magic_getsubstr>, magic_gettaint +X<magic_gettaint>, magic_getuvar X<magic_getuvar>, magic_getvec +X<magic_getvec>, magic_killbackrefs X<magic_killbackrefs>, magic_len +X<magic_len>, magic_methcall1 X<magic_methcall1>, magic_methpack +X<magic_methpack>, magic_nextpack X<magic_nextpack>, magic_regdata_cnt +X<magic_regdata_cnt>, magic_regdatum_get X<magic_regdatum_get>, +magic_regdatum_set X<magic_regdatum_set>, magic_scalarpack +X<magic_scalarpack>, magic_set X<magic_set>, magic_set_all_env +X<magic_set_all_env>, magic_setamagic X<magic_setamagic>, magic_setarylen +X<magic_setarylen>, magic_setcollxfrm X<magic_setcollxfrm>, magic_setdbline +X<magic_setdbline>, magic_setdefelem X<magic_setdefelem>, magic_setenv +X<magic_setenv>, magic_setisa X<magic_setisa>, magic_setmglob +X<magic_setmglob>, magic_setnkeys X<magic_setnkeys>, magic_setpack +X<magic_setpack>, magic_setpos X<magic_setpos>, magic_setregexp +X<magic_setregexp>, magic_setsig X<magic_setsig>, magic_setsubstr +X<magic_setsubstr>, magic_settaint X<magic_settaint>, magic_setutf8 +X<magic_setutf8>, magic_setuvar X<magic_setuvar>, magic_setvec +X<magic_setvec>, magic_sizepack X<magic_sizepack>, magic_wipepack +X<magic_wipepack>, make_matcher X<make_matcher>, make_trie X<make_trie>, +make_trie_failtable X<make_trie_failtable>, malloc_good_size +X<malloc_good_size>, malloced_size X<malloced_size>, matcher_matches_sv +X<matcher_matches_sv>, measure_struct X<measure_struct>, mem_collxfrm +X<mem_collxfrm>, mem_log_common X<mem_log_common>, mess_alloc +X<mess_alloc>, method_common X<method_common>, missingterm X<missingterm>, +mod X<mod>, mode_from_discipline X<mode_from_discipline>, modkids +X<modkids>, more_bodies X<more_bodies>, more_sv X<more_sv>, +mro_clean_isarev X<mro_clean_isarev>, mro_gather_and_rename +X<mro_gather_and_rename>, mro_meta_dup X<mro_meta_dup>, mro_meta_init +X<mro_meta_init>, mul128 X<mul128>, mulexp10 X<mulexp10>, +munge_qwlist_to_paren_list X<munge_qwlist_to_paren_list>, my_attrs +X<my_attrs>, my_betoh16 X<my_betoh16>, my_betoh32 X<my_betoh32>, my_betoh64 +X<my_betoh64>, my_betohi X<my_betohi>, my_betohl X<my_betohl>, my_betohs +X<my_betohs>, my_clearenv X<my_clearenv>, my_exit_jump X<my_exit_jump>, +my_htobe16 X<my_htobe16>, my_htobe32 X<my_htobe32>, my_htobe64 +X<my_htobe64>, my_htobei X<my_htobei>, my_htobel X<my_htobel>, my_htobes +X<my_htobes>, my_htole16 X<my_htole16>, my_htole32 X<my_htole32>, +my_htole64 X<my_htole64>, my_htolei X<my_htolei>, my_htolel X<my_htolel>, +my_htoles X<my_htoles>, my_kid X<my_kid>, my_letoh16 X<my_letoh16>, +my_letoh32 X<my_letoh32>, my_letoh64 X<my_letoh64>, my_letohi X<my_letohi>, +my_letohl X<my_letohl>, my_letohs X<my_letohs>, my_lstat_flags +X<my_lstat_flags>, my_stat_flags X<my_stat_flags>, my_swabn X<my_swabn>, +my_unexec X<my_unexec>, need_utf8 X<need_utf8>, newDEFSVOP X<newDEFSVOP>, +newGIVWHENOP X<newGIVWHENOP>, newGP X<newGP>, newMADPROP X<newMADPROP>, +newMADsv X<newMADsv>, newTOKEN X<newTOKEN>, new_constant X<new_constant>, +new_he X<new_he>, new_logop X<new_logop>, new_warnings_bitfield +X<new_warnings_bitfield>, next_symbol X<next_symbol>, nextargv X<nextargv>, +nextchar X<nextchar>, no_bareword_allowed X<no_bareword_allowed>, +no_fh_allowed X<no_fh_allowed>, no_op X<no_op>, not_a_number +X<not_a_number>, nuke_stacks X<nuke_stacks>, num_overflow X<num_overflow>, +oopsAV X<oopsAV>, oopsHV X<oopsHV>, op_clear X<op_clear>, op_const_sv +X<op_const_sv>, op_getmad X<op_getmad>, op_getmad_weak X<op_getmad_weak>, +op_refcnt_dec X<op_refcnt_dec>, op_refcnt_inc X<op_refcnt_inc>, op_xmldump +X<op_xmldump>, open_script X<open_script>, opt_scalarhv X<opt_scalarhv>, +pack_rec X<pack_rec>, package X<package>, package_version +X<package_version>, pad_add_name_sv X<pad_add_name_sv>, pad_compname_type +X<pad_compname_type>, pad_peg X<pad_peg>, padlist_dup X<padlist_dup>, +parse_body X<parse_body>, parse_unicode_opts X<parse_unicode_opts>, +parser_free X<parser_free>, path_is_absolute X<path_is_absolute>, peep +X<peep>, pending_Slabs_to_ro X<pending_Slabs_to_ro>, pidgone X<pidgone>, +pm_description X<pm_description>, pmop_xmldump X<pmop_xmldump>, pmruntime +X<pmruntime>, pmtrans X<pmtrans>, populate_isa X<populate_isa>, prepend_madprops X<prepend_madprops>, printbuf X<printbuf>, process_special_blocks X<process_special_blocks>, ptr_table_find X<ptr_table_find>, put_byte X<put_byte>, qerror X<qerror>, qsortsvu X<qsortsvu>, re_croak2 X<re_croak2>, readpipe_override X<readpipe_override>, ref_array_or_hash X<ref_array_or_hash>, -refcounted_he_fetch X<refcounted_he_fetch>, refcounted_he_new_common -X<refcounted_he_new_common>, refcounted_he_value X<refcounted_he_value>, -refkids X<refkids>, refto X<refto>, reg X<reg>, -reg_check_named_buff_matched X<reg_check_named_buff_matched>, -reg_named_buff X<reg_named_buff>, reg_named_buff_iter -X<reg_named_buff_iter>, reg_namedseq X<reg_namedseq>, reg_node X<reg_node>, -reg_numbered_buff_fetch X<reg_numbered_buff_fetch>, +refcounted_he_value X<refcounted_he_value>, refkids X<refkids>, refto +X<refto>, reg X<reg>, reg_check_named_buff_matched +X<reg_check_named_buff_matched>, reg_named_buff X<reg_named_buff>, +reg_named_buff_iter X<reg_named_buff_iter>, reg_namedseq X<reg_namedseq>, +reg_node X<reg_node>, reg_numbered_buff_fetch X<reg_numbered_buff_fetch>, reg_numbered_buff_length X<reg_numbered_buff_length>, reg_numbered_buff_store X<reg_numbered_buff_store>, reg_qr_package X<reg_qr_package>, reg_recode X<reg_recode>, reg_scan_name @@ -6641,24 +6823,24 @@ reginclass X<reginclass>, reginsert X<reginsert>, regmatch X<regmatch>, regpiece X<regpiece>, regpposixcc X<regpposixcc>, regprop X<regprop>, regrepeat X<regrepeat>, regtail X<regtail>, regtail_study X<regtail_study>, regtry X<regtry>, reguni X<reguni>, regwhite X<regwhite>, report_evil_fh -X<report_evil_fh>, require_tie_mod X<require_tie_mod>, restore_magic -X<restore_magic>, rsignal_restore X<rsignal_restore>, rsignal_save -X<rsignal_save>, run_body X<run_body>, run_user_filter X<run_user_filter>, -rxres_free X<rxres_free>, rxres_restore X<rxres_restore>, rxres_save -X<rxres_save>, same_dirent X<same_dirent>, save_freeop X<save_freeop>, -save_hek_flags X<save_hek_flags>, save_hints X<save_hints>, save_lines -X<save_lines>, save_magic X<save_magic>, save_op X<save_op>, -save_pushi32ptr X<save_pushi32ptr>, save_pushptri32ptr -X<save_pushptri32ptr>, save_pushptrptr X<save_pushptrptr>, save_scalar_at -X<save_scalar_at>, sawparens X<sawparens>, scalar X<scalar>, -scalar_mod_type X<scalar_mod_type>, scalarboolean X<scalarboolean>, -scalarkids X<scalarkids>, scalarseq X<scalarseq>, scalarvoid X<scalarvoid>, -scan_commit X<scan_commit>, scan_const X<scan_const>, scan_formline -X<scan_formline>, scan_heredoc X<scan_heredoc>, scan_ident X<scan_ident>, -scan_inputsymbol X<scan_inputsymbol>, scan_pat X<scan_pat>, scan_str -X<scan_str>, scan_subst X<scan_subst>, scan_trans X<scan_trans>, scan_word -X<scan_word>, scope X<scope>, search_const X<search_const>, sequence -X<sequence>, sequence_num X<sequence_num>, sequence_tail X<sequence_tail>, +X<report_evil_fh>, report_wrongway_fh X<report_wrongway_fh>, +require_tie_mod X<require_tie_mod>, restore_magic X<restore_magic>, rpeep +X<rpeep>, rsignal_restore X<rsignal_restore>, rsignal_save X<rsignal_save>, +run_body X<run_body>, run_user_filter X<run_user_filter>, rxres_free +X<rxres_free>, rxres_restore X<rxres_restore>, rxres_save X<rxres_save>, +same_dirent X<same_dirent>, save_hek_flags X<save_hek_flags>, save_lines +X<save_lines>, save_magic X<save_magic>, save_pushptri32ptr +X<save_pushptri32ptr>, save_scalar_at X<save_scalar_at>, sawparens +X<sawparens>, scalar X<scalar>, scalar_mod_type X<scalar_mod_type>, +scalarboolean X<scalarboolean>, scalarkids X<scalarkids>, scalarseq +X<scalarseq>, scalarvoid X<scalarvoid>, scan_commit X<scan_commit>, +scan_const X<scan_const>, scan_formline X<scan_formline>, scan_heredoc +X<scan_heredoc>, scan_ident X<scan_ident>, scan_inputsymbol +X<scan_inputsymbol>, scan_pat X<scan_pat>, scan_str X<scan_str>, scan_subst +X<scan_subst>, scan_trans X<scan_trans>, scan_word X<scan_word>, +search_const X<search_const>, sequence X<sequence>, sequence_num +X<sequence_num>, sequence_tail X<sequence_tail>, set_regclass_bit +X<set_regclass_bit>, set_regclass_bit_fold X<set_regclass_bit_fold>, share_hek_flags X<share_hek_flags>, sighandler X<sighandler>, simplify_sort X<simplify_sort>, skipspace X<skipspace>, skipspace0 X<skipspace0>, skipspace1 X<skipspace1>, skipspace2 X<skipspace2>, softref2xv @@ -6670,36 +6852,42 @@ X<strip_return>, study_chunk X<study_chunk>, sub_crush_depth X<sub_crush_depth>, sublex_done X<sublex_done>, sublex_push X<sublex_push>, sublex_start X<sublex_start>, sv_2iuv_common X<sv_2iuv_common>, sv_2iuv_non_preserve X<sv_2iuv_non_preserve>, sv_add_backref -X<sv_add_backref>, sv_catxmlpvn X<sv_catxmlpvn>, sv_catxmlsv -X<sv_catxmlsv>, sv_del_backref X<sv_del_backref>, sv_dup_inc_multiple -X<sv_dup_inc_multiple>, sv_exp_grow X<sv_exp_grow>, sv_free2 X<sv_free2>, -sv_i_ncmp X<sv_i_ncmp>, sv_kill_backrefs X<sv_kill_backrefs>, sv_ncmp -X<sv_ncmp>, sv_pos_b2u_midway X<sv_pos_b2u_midway>, sv_pos_u2b_cached -X<sv_pos_u2b_cached>, sv_pos_u2b_forwards X<sv_pos_u2b_forwards>, -sv_pos_u2b_midway X<sv_pos_u2b_midway>, sv_release_COW X<sv_release_COW>, -sv_setsv_cow X<sv_setsv_cow>, sv_unglob X<sv_unglob>, sv_xmlpeek -X<sv_xmlpeek>, swallow_bom X<swallow_bom>, swash_get X<swash_get>, -to_byte_substr X<to_byte_substr>, to_utf8_substr X<to_utf8_substr>, -token_free X<token_free>, token_getmad X<token_getmad>, tokenize_use -X<tokenize_use>, tokeq X<tokeq>, tokereport X<tokereport>, +X<sv_add_backref>, sv_catxmlpv X<sv_catxmlpv>, sv_catxmlpvn +X<sv_catxmlpvn>, sv_catxmlsv X<sv_catxmlsv>, sv_compile_2op_is_broken +X<sv_compile_2op_is_broken>, sv_del_backref X<sv_del_backref>, +sv_dup_common X<sv_dup_common>, sv_dup_inc_multiple X<sv_dup_inc_multiple>, +sv_exp_grow X<sv_exp_grow>, sv_free2 X<sv_free2>, sv_i_ncmp X<sv_i_ncmp>, +sv_kill_backrefs X<sv_kill_backrefs>, sv_ncmp X<sv_ncmp>, sv_pos_b2u_midway +X<sv_pos_b2u_midway>, sv_pos_u2b_cached X<sv_pos_u2b_cached>, +sv_pos_u2b_forwards X<sv_pos_u2b_forwards>, sv_pos_u2b_midway +X<sv_pos_u2b_midway>, sv_release_COW X<sv_release_COW>, sv_setsv_cow +X<sv_setsv_cow>, sv_unglob X<sv_unglob>, sv_xmlpeek X<sv_xmlpeek>, +swallow_bom X<swallow_bom>, swash_get X<swash_get>, tied_method +X<tied_method>, to_byte_substr X<to_byte_substr>, to_utf8_substr +X<to_utf8_substr>, token_free X<token_free>, token_getmad X<token_getmad>, +tokenize_use X<tokenize_use>, tokeq X<tokeq>, tokereport X<tokereport>, too_few_arguments X<too_few_arguments>, too_many_arguments -X<too_many_arguments>, uiv_2buf X<uiv_2buf>, unpack_rec X<unpack_rec>, -unshare_hek X<unshare_hek>, unshare_hek_or_pvn X<unshare_hek_or_pvn>, +X<too_many_arguments>, try_amagic_bin X<try_amagic_bin>, try_amagic_un +X<try_amagic_un>, uiv_2buf X<uiv_2buf>, unpack_rec X<unpack_rec>, +unreferenced_to_tmp_stack X<unreferenced_to_tmp_stack>, unshare_hek +X<unshare_hek>, unshare_hek_or_pvn X<unshare_hek_or_pvn>, unwind_handler_stack X<unwind_handler_stack>, update_debugger_info X<update_debugger_info>, usage X<usage>, utf16_textfilter -X<utf16_textfilter>, utf8_mg_pos_cache_update X<utf8_mg_pos_cache_update>, -utilize X<utilize>, validate_suid X<validate_suid>, varname X<varname>, -vdie X<vdie>, vdie_common X<vdie_common>, vdie_croak_common -X<vdie_croak_common>, visit X<visit>, vivify_defelem X<vivify_defelem>, -vivify_ref X<vivify_ref>, wait4pid X<wait4pid>, watch X<watch>, +X<utf16_textfilter>, utf8_mg_len_cache_update X<utf8_mg_len_cache_update>, +utf8_mg_pos_cache_update X<utf8_mg_pos_cache_update>, utilize X<utilize>, +validate_suid X<validate_suid>, varname X<varname>, visit X<visit>, +vivify_defelem X<vivify_defelem>, vivify_ref X<vivify_ref>, wait4pid +X<wait4pid>, watch X<watch>, with_queued_errors X<with_queued_errors>, write_no_mem X<write_no_mem>, write_to_stderr X<write_to_stderr>, xmldump_all X<xmldump_all>, xmldump_all_perl X<xmldump_all_perl>, xmldump_attr X<xmldump_attr>, xmldump_eval X<xmldump_eval>, xmldump_form X<xmldump_form>, xmldump_indent X<xmldump_indent>, xmldump_packsubs X<xmldump_packsubs>, xmldump_packsubs_perl X<xmldump_packsubs_perl>, xmldump_sub X<xmldump_sub>, xmldump_sub_perl X<xmldump_sub_perl>, -xmldump_vindent X<xmldump_vindent>, yyerror X<yyerror>, yylex X<yylex>, -yyparse X<yyparse>, yywarn X<yywarn> +xmldump_vindent X<xmldump_vindent>, xs_apiversion_bootcheck +X<xs_apiversion_bootcheck>, xs_version_bootcheck X<xs_version_bootcheck>, +yyerror X<yyerror>, yylex X<yylex>, yyparse X<yyparse>, yyunlex X<yyunlex>, +yywarn X<yywarn> =item AUTHORS @@ -6809,106 +6997,223 @@ PerlIO_apply_layers(f,mode,layers), PerlIO_binmode(f,ptype,imode,layers), =back -=head2 perlhack - How to hack at the Perl internals +=head2 perlhack - How to hack on Perl =over 4 =item DESCRIPTION -Does concept match the general goals of Perl?, Where is the -implementation?, Backwards compatibility, Could it be a module instead?, Is -the feature generic enough?, Does it potentially introduce new bugs?, Does -it preclude other desirable features?, Is the implementation robust?, Is -the implementation generic enough to be portable?, Is the implementation -tested?, Is there enough documentation?, Is there another way to do it?, -Does it create too much work?, Patches speak louder than words +=item SUPER QUICK PATCH GUIDE + +Check out the source repository, Make your change, Test your change, Commit +your change, Send your change to perlbug, Thank you + +=item BUG REPORTING + +=item PERL 5 PORTERS + +=over 4 + +=item perl-changes mailing list + +=back + +=item GETTING THE PERL SOURCE =over 4 -=item Keeping in sync +=item Read access via Git + +=item Read access via the web + +=item Read access via rsync -=item Perlbug administration +=item Write access via git + +=back + +=item PATCHING PERL + +=over 4 =item Submitting patches -L<perlguts>, L<perlxstut> and L<perlxs>, L<perlapi>, -F<Porting/pumpkin.pod>, The perl5-porters FAQ +=item Getting your patch accepted -=item Finding Your Way Around +Why, What, How -Core modules, Tests, Documentation, Configure, Interpreter +=item Patching a core module -=item Elements of the interpreter +=item Updating perldelta -Startup, Parsing, Optimization, Running, Exception handing +=item What makes for a good patch? -=item Internal Variable Types +=back -=item Op Trees +=item TESTING -=item Stacks +F<t/base> and F<t/comp>, F<t/cmd>, F<t/run>, F<t/io> and F<t/op>, +Everything else -Argument stack, Mark stack, Save stack +=over 4 -=item Millions of Macros +=item Special C<make test> targets -=item The .i Targets +test_porting, coretest, test.deparse, test.taintwarn, minitest, +test.valgrind check.valgrind utest.valgrind ucheck.valgrind, test.torture +torturetest, utest ucheck test.utf8 check.utf8, minitest.utf16 test.utf16, +test_harness, test-notty test_notty + +=item Parallel tests + +=item Running tests by hand + +=item Using F<t/harness> for testing + +-v, -torture, -re=PATTERN, -re LIST OF PATTERNS, PERL_CORE=1, +PERL_DESTRUCT_LEVEL=2, PERL, PERL_SKIP_TTY_TEST, PERL_TEST_Net_Ping, +PERL_TEST_NOVREXX, PERL_TEST_NUMCONVERTS =back -=item SOURCE CODE STATIC ANALYSIS +=item MORE READING FOR GUTS HACKERS + +L<perlsource>, L<perlinterp>, L<perlhacktut>, L<perlhacktips>, L<perlguts>, +L<perlxstut> and L<perlxs>, L<perlapi>, F<Porting/pumpkin.pod>, The +perl5-porters FAQ + +=item CPAN TESTERS AND PERL SMOKERS + +=item WHAT NEXT? =over 4 -=item lint, splint +=item "The Road goes ever on and on, down from the door where it began." -=item Coverity +=item Metaphoric Quotations -=item cpd (cut-and-paste detector) +=back -=item gcc warnings +=item AUTHOR -=item Warnings of other C compilers +=back -=item DEBUGGING +=head2 perlsource - A guide to the Perl source tree -=item Poking at Perl +=over 4 -=item Using a source-level debugger +=item DESCRIPTION -run [args], break function_name, break source.c:xxx, step, next, continue, -finish, 'enter', print +=item FINDING YOUR WAY AROUND -=item gdb macro support +=over 4 -=item Dumping Perl Data Structures +=item C code -=item Patching +=item Core modules -=item Patching a core module +F<lib/>, F<ext/>, F<dist/>, F<cpan/> -=item Adding a new function to the core +=item Tests -=item Writing a test +Module tests, F<t/base/>, F<t/cmd/>, F<t/comp/>, F<t/io/>, F<t/mro/>, +F<t/op/>, F<t/re/>, F<t/run/>, F<t/uni/>, F<t/win32/>, F<t/porting/>, +F<t/lib/>, F<t/x2p> -F<t/base/>, F<t/cmd/>, F<t/comp/>, F<t/io/>, F<t/lib/>, F<t/mro/>, -F<t/op/>, F<t/re/>, F<t/run/>, F<t/uni/>, F<t/win32/>, F<t/x2p>, t/base -t/comp, t/cmd t/run t/io t/op, t/lib ext lib +=item Documentation -=item Special Make Test Targets +=item Hacking toolks and documentation -coretest, test.deparse, test.taintwarn, minitest, test.valgrind -check.valgrind utest.valgrind ucheck.valgrind, test.third check.third -utest.third ucheck.third, test.torture torturetest, utest ucheck test.utf8 -check.utf8, minitest.utf16 test.utf16, test_harness, Parallel tests +F<check*>, F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm>, +F<podtidy> -=item Running tests by hand +=item Build system --v, -torture, -re=PATTERN, -re LIST OF PATTERNS, PERL_CORE=1, -PERL_DESTRUCT_LEVEL=2, PERL, PERL_SKIP_TTY_TEST, PERL_TEST_Net_Ping, -PERL_TEST_NOVREXX, PERL_TEST_NUMCONVERTS +=item F<AUTHORS> + +=item F<MANIFEST> + +=back + +=back + +=head2 perlinterp - An overview of the Perl interpreter + +=over 4 + +=item DESCRIPTION + +=item ELEMENTS OF THE INTERPRETER + +=over 4 + +=item Startup + +=item Parsing + +=item Optimization + +=item Running + +=item Exception handing + +=item INTERNAL VARIABLE TYPES + +=back + +=item OP TREES + +=item STACKS + +=over 4 + +=item Argument stack + +=item Mark stack + +=item Save stack + +=back + +=item MILLIONS OF MACROS + +=item FURTHER READING + +=back + +=head2 perlhacktut - Walk through the creation of a simple C code patch + +=over 4 + +=item DESCRIPTION + +=item EXAMPLE OF A SIMPLE PATCH + +=over 4 + +=item Writing the patch + +=item Testing the patch + +=item Documenting the patch + +=item Submit -=item Common problems when patching Perl source code +=back + +=item AUTHOR + +=back + +=head2 perlhacktips - Tips for Perl core C code hacking + +=over 4 + +=item DESCRIPTION + +=item COMMON PROBLEMS + +=over 4 =item Perl environment problems @@ -6920,29 +7225,55 @@ PERL_TEST_NOVREXX, PERL_TEST_NUMCONVERTS =back -=item EXTERNAL TOOLS FOR DEBUGGING PERL +=item DEBUGGING =over 4 -=item Rational Software's Purify +=item Poking at Perl + +=item Using a source-level debugger + +run [args], break function_name, break source.c:xxx, step, next, continue, +finish, 'enter', print -=item Purify on Unix +=item gdb macro support --Accflags=-DPURIFY, -Doptimize='-g', -Uusemymalloc, -Dusemultiplicity +=item Dumping Perl Data Structures -=item Purify on NT +=back +=item SOURCE CODE STATIC ANALYSIS + +=over 4 + +=item lint, splint + +=item Coverity + +=item cpd (cut-and-paste detector) + +=item gcc warnings + +=item Warnings of other C compilers + +=back + +=item MEMORY DEBUGGERS + +=over 4 + +=item Rational Software's Purify + +-Accflags=-DPURIFY, -Doptimize='-g', -Uusemymalloc, -Dusemultiplicity, DEFINES, USE_MULTI = define, #PERL_MALLOC = define, CFG = Debug =item valgrind -=item Compaq's/Digital's/HP's Third Degree - -=item PERL_DESTRUCT_LEVEL +=back -=item PERL_MEM_LOG +=item PROFILING -=item Profiling +=over 4 =item Gprof Profiling @@ -6950,33 +7281,32 @@ DEFINES, USE_MULTI = define, #PERL_MALLOC = define, CFG = Debug =item GCC gcov Profiling -=item Pixie Profiling +=back --h, -l, -p[rocedures], -h[eavy], -i[nvocations], -l[ines], -testcoverage, --z[ero] +=item MISCELLANEOUS TRICKS -=item Miscellaneous tricks +=over 4 -=back +=item PERL_DESTRUCT_LEVEL -=item CONCLUSION +=item PERL_MEM_LOG -I<The Road goes ever on and on, down from the door where it began.> +=item DDD over gdb -=over 4 +=item Poison -=item Metaphoric Quotations +=item Read-only optrees + +=item The .i Targets =back =item AUTHOR -=item SEE ALSO - =back =head2 perlpolicy - Various and sundry policies and commitments related to -the perl core +the Perl core =over 4 @@ -7010,78 +7340,109 @@ experimental, deprecated, discouraged, removed =back +=item DOCUMENTATION + =item CREDITS =back -=head2 perlrepository - Using the Perl source repository +=head2 perlgit - Detailed information about git and the Perl repository =over 4 -=item SYNOPSIS +=item DESCRIPTION + +=item CLONING THE REPOSITORY -=item Getting access to the repository +=item WORKING WITH THE REPOSITORY =over 4 -=item Read access via the web +=item Finding out your status -=item Read access via Git +=item Patch workflow -=item Write access to the repository +=item Committing your changes -=item A note on camel and dromedary +=item Using git to send patch emails + +=item A note on derived files + +=item Cleaning a working directory + +=item Bisecting + +=item Topic branches and rewriting history =back -=item Overview of the repository +=item WRITE ACCESS TO THE GIT REPOSITORY =over 4 -=item Finding out your status +=item Committing to blead + +=item Committing to maintenance versions + +=item Grafts + +=item Merging from a branch via GitHub + +=item A note on camel and dromedary =back -=item Submitting a patch +=back + +=head2 perlbook - Books about and related to Perl =over 4 -=item Using git to send patch emails +=item DESCRIPTION -=item A note on derived files +=over 4 -=item Getting your patch accepted +=item The most popular books -Commit message, What, Why, How, Comments, Comments, Comments, Style, -Testsuite +I<Programming Perl> (the "Camel Book"):, I<The Perl Cookbook> (the "Ram +Book"):, I<Learning Perl> (the "Llama Book"), I<Intermediate Perl> (the +"Alpaca Book") -=back +=item References -=item Accepting a patch +I<Perl 5 Pocket Reference>, I<Perl Debugger Pocket Reference>, I<Regular +Expression Pocket Reference> -=item Cleaning a working directory +=item Tutorials -=item Bisecting +I<Beginning Perl>, I<Learning Perl>, I<Intermediate Perl> (the "Alpaca +Book"), I<Mastering Perl>, I<Effective Perl Programming> -=item Submitting a patch via GitHub +=item Task-Oriented -=item Merging from a branch via GitHub +I<Writing Perl Modules for CPAN>, I<The Perl Cookbook>, I<Automating System +Administration with Perl>, I<Real World SQL Server Administration with +Perl> -=item Topic branches and rewriting history +=item Special Topics -=item Committing to maintenance versions +I<Regular Expressions Cookbook>, I<Programming the Perl DBI>, I<Perl Best +Practices>, I<Higher-Order Perl>, I<Mastering Regular Expressions>, +I<Network Programming with Perl>, I<Perl Template Toolkit>, I<Object +Oriented Perl>, I<Data Munging with Perl>, I<Mastering Perl/Tk>, +I<Extending and Embedding Perl>, I<Pro Perl Debugging> -=item Grafts +=item Free (as in beer) books -=item SEE ALSO +=item Other interesting, non-Perl books -=back +I<Programming Pearls>, I<More Programming Pearls> -=head2 perlbook - Perl book information +=item A note on freshness -=over 4 +=item Get your book listed -=item DESCRIPTION +=back =back @@ -7093,9 +7454,9 @@ Testsuite =over 4 -=item Where to find the community +=item Where to Find the Community -=item Mailing lists and Newsgroups +=item Mailing Lists and Newsgroups =item IRC @@ -7129,12 +7490,8 @@ L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/> =over 4 -=item Improve Porting/cmpVERSION.pl to work from git tags - =item Migrate t/ from custom TAP generation -=item Test that regen.pl was run - =item Automate perldelta generation Modules and Pragmata, New Documentation, New Tests @@ -7157,8 +7514,6 @@ Modules and Pragmata, New Documentation, New Tests =item Dual life everything -=item Move dual-life pod/*.PL into ext - =item POSIX memory footprint =item embed.pl/makedef.pl @@ -7167,7 +7522,7 @@ Modules and Pragmata, New Documentation, New Tests =item profile installman -=item enable lexical enabling/disabling of inidvidual warnings +=item enable lexical enabling/disabling of individual warnings =back @@ -7327,6 +7682,8 @@ C<cc> (in F<cc.U>), C<ld> (in F<dlsrc.U>) =item optimize tail-calls +=item Add C<00dddd> + =back =item Big projects @@ -7339,8 +7696,6 @@ C<cc> (in F<cc.U>), C<ld> (in F<dlsrc.U>) =item (?{...}) closures in regexps -=item A re-entrant regexp engine - =item Add class set operations to regexp engine =back @@ -7421,27 +7776,1467 @@ B<-V> =back -=head2 perldelta - what is new for perl v5.12.3 +=head2 perldelta - what is new for perl v5.14.2 =over 4 =item DESCRIPTION +=item Core Enhancements + +=item Security + +=over 4 + +=item C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC +(CVE-2011-2728). + +=item C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939) + +=back + =item Incompatible Changes +=item Deprecations + +=item Modules and Pragmata + +=over 4 + +=item New Modules and Pragmata + +=item Updated Modules and Pragmata + +=item Removed Modules and Pragmata + +=back + +=item Platform Support + +=over 4 + +=item New Platforms + +=item Discontinued Platforms + +=item Platform-Specific Notes + +HP-UX PA-RISC/64 now supports gcc-4.x, Building on OS X 10.7 Lion and Xcode +4 works again + +=back + +=item Bug Fixes + +=item Known Problems + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5142delta, perldelta - what is new for perl v5.14.2 + +=over 4 + +=item DESCRIPTION + =item Core Enhancements +=item Security + =over 4 -=item C<keys>, C<values> work on arrays +=item C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC +(CVE-2011-2728). + +=item C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939) + +=back + +=item Incompatible Changes + +=item Deprecations + +=item Modules and Pragmata + +=over 4 + +=item New Modules and Pragmata + +=item Updated Modules and Pragmata + +=item Removed Modules and Pragmata + +=back + +=item Platform Support + +=over 4 + +=item New Platforms + +=item Discontinued Platforms + +=item Platform-Specific Notes + +HP-UX PA-RISC/64 now supports gcc-4.x, Building on OS X 10.7 Lion and Xcode +4 works again =back =item Bug Fixes +=item Known Problems + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5141delta - what is new for perl v5.14.1 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=item Security + +=item Incompatible Changes + +=item Deprecations + +=item Modules and Pragmata + +=over 4 + +=item New Modules and Pragmata + +=item Updated Modules and Pragmata + +=item Removed Modules and Pragmata + +=back + +=item Documentation + +=over 4 + +=item New Documentation + +=item Changes to Existing Documentation + +=back + +=item Diagnostics + +=over 4 + +=item New Diagnostics + +=item Changes to Existing Diagnostics + +=back + +=item Utility Changes + +=item Configuration and Compilation + +=item Testing + +=item Platform Support + +=over 4 + +=item New Platforms + +=item Discontinued Platforms + +=item Platform-Specific Notes + +=back + +=item Internal Changes + +=item Bug Fixes + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5140delta - what is new for perl v5.14.0 + +=over 4 + +=item DESCRIPTION + +=item Notice + +=item Core Enhancements + +=over 4 + +=item Unicode + +=item Regular Expressions + +=item Syntactical Enhancements + +=item Exception Handling + +=item Other Enhancements + +C<-d:-foo>, C<-d:-foo=bar> + +=item New C APIs + +=back + +=item Security + +=over 4 + +=item User-defined regular expression properties + +=back + +=item Incompatible Changes + +=over 4 + +=item Regular Expressions and String Escapes + +=item Stashes and Package Variables + +=item Changes to Syntax or to Perl Operators + +=item Threads and Processes + +=item Configuration + +=back + +=item Deprecations + +=over 4 + +=item Omitting a space between a regular expression and subsequent word + +=item C<\cI<X>> + +=item C<"\b{"> and C<"\B{"> + +=item Perl 4-era .pl libraries + +=item List assignment to C<$[> + +=item Use of qw(...) as parentheses + +=item C<\N{BELL}> + +=item C<?PATTERN?> + +=item Tie functions on scalars holding typeglobs + +=item User-defined case-mapping + +=item Deprecated modules + +L<Devel::DProf> + +=back + +=item Performance Enhancements + +=over 4 + +=item "Safe signals" optimisation + +=item Optimisation of shift() and pop() calls without arguments + +=item Optimisation of regexp engine string comparison work + +=item Regular expression compilation speed-up + +=item String appending is 100 times faster + +=item Eliminate C<PL_*> accessor functions under ithreads + +=item Freeing weak references + +=item Lexical array and hash assignments + +=item C<@_> uses less memory + +=item Size optimisations to SV and HV structures + +=item Memory consumption improvements to Exporter + +=item Memory savings for weak references + +=item C<%+> and C<%-> use less memory + +=item Multiple small improvements to threads + +=item Adjacent pairs of nextstate opcodes are now optimized away + +=back + +=item Modules and Pragmata + +=over 4 + +=item New Modules and Pragmata + +=item Updated Modules and Pragma + +much less configuration dialog hassle, support for F<META/MYMETA.json>, +support for L<local::lib>, support for L<HTTP::Tiny> to reduce the +dependency on FTP sites, automatic mirror selection, iron out all known +bugs in configure_requires, support for distributions compressed with +L<bzip2(1)>, allow F<Foo/Bar.pm> on the command line to mean C<Foo::Bar>, +charinfo(), charscript(), charblock() + +=item Removed Modules and Pragmata + +=back + +=item Documentation + +=over 4 + +=item New Documentation + +=item Changes to Existing Documentation + +=back + +=item Diagnostics + +=over 4 + +=item New Diagnostics + +Closure prototype called, Insecure user-defined property %s, panic: gp_free +failed to free glob pointer - something is repeatedly re-creating entries, +Parsing code internal error (%s), refcnt: fd %d%s, Regexp modifier "/%c" +may not appear twice, Regexp modifiers "/%c" and "/%c" are mutually +exclusive, Using !~ with %s doesn't make sense, "\b{" is deprecated; use +"\b\{" instead, "\B{" is deprecated; use "\B\{" instead, Operation "%s" +returns its argument for .., Use of qw(...) as parentheses is deprecated + +=item Changes to Existing Diagnostics + +=back + +=item Utility Changes + +=item Configuration and Compilation + +=item Platform Support + +=over 4 + +=item New Platforms + +AIX + +=item Discontinued Platforms + +Apollo DomainOS, MacOS Classic + +=item Platform-Specific Notes + +=back + +=item Internal Changes + +=over 4 + +=item New APIs + +=item C API Changes + +=item Deprecated C APIs + +C<Perl_ptr_table_clear>, C<sv_compile_2op>, C<find_rundefsvoffset>, +C<CALL_FPTR> and C<CPERLscope> + +=item Other Internal Changes + +=back + +=item Selected Bug Fixes + +=over 4 + +=item I/O + +=item Regular Expression Bug Fixes + +=item Syntax/Parsing Bugs + +=item Stashes, Globs and Method Lookup + +Aliasing packages by assigning to globs [perl #77358], Deleting packages by +deleting their containing stash elements, Undefining the glob containing a +package (C<undef *Foo::>), Undefining an ISA glob (C<undef *Foo::ISA>), +Deleting an ISA stash element (C<delete $Foo::{ISA}>), Sharing @ISA arrays +between classes (via C<*Foo::ISA = \@Bar::ISA> or C<*Foo::ISA = *Bar::ISA>) +[perl #77238] + +=item Unicode + +=item Ties, Overloading and Other Magic + +=item The Debugger + +=item Threads + +=item Scoping and Subroutines + +=item Signals + +=item Miscellaneous Memory Leaks + +=item Memory Corruption and Crashes + +=item Fixes to Various Perl Operators + +=item Bugs Relating to the C API + +=back + +=item Known Problems + +=item Errata + +=over 4 + +=item keys(), values(), and each() work on arrays + +=item split() and C<@_> + +=back + +=item Obituary + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl51311delta - what is new for perl v5.13.11 + +=over 4 + +=item DESCRIPTION + +=item Security + +=over 4 + +=item User-defined regular expression properties + +=back + +=item Incompatible Changes + +=over 4 + +=item local($_) will strip all magic from $_ + +=item Passing references to warn() + +=item fork() emulation will not wait for signalled children + +=item Perl source code is read in text mode on Windows + +=back + +=item Performance Enhancements + +=item Modules and Pragmata + +=over 4 + +=item Updated Modules and Pragmata + +charinfo(), charscript(), charblock() + +=back + +=item Documentation + +=over 4 + +=item Changes to Existing Documentation + +=back + +=item Diagnostics + +=over 4 + +=item New Diagnostics + +=back + +=item Testing + +=item Selected Bug Fixes + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl51310delta - what is new for perl v5.13.10 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item The new regular expression modifiers available in suffix form + +=item Add C<\p{Titlecase}> as a synonym for C<\p{Title}> + +=item New regular expression modifier option C</aa> + +=item New warnings categories for problematic (non-)Unicode code points. + +=back + +=item Incompatible Changes + +=over 4 + +=item Most C<\p{}> properties are now immune from case-insensitive matching + +=item regex: \p{} in pattern implies Unicode semantics + +=item add GvCV_set() and GvGP_set() macros and change GvGP() + +=item _swash_inversion_hash is no longer exported as part of the API + +=item Unreferenced objects in global destruction + +=item C<close> on shared pipes + +=back + +=item Deprecations + +Deprecated Modules, L<Devel::DProf> + +=over 4 + +=item User-defined case-mapping + +=back + +=item Modules and Pragmata + +=over 4 + +=item New Modules and Pragmata + +=item Updated Modules and Pragmata + +=back + +=item Documentation + +=over 4 + +=item Changes to Existing Documentation + +=back + +=item Diagnostics + +=over 4 + +=item New Diagnostics + +"\b{" is deprecated; use "\b\{" instead, "\B{" is deprecated; use "\B\{" +instead, regcomp: Add warning if \p is used under locale. (fb2e24c), panic: +gp_free failed to free glob pointer - something is repeatedly re-creating +entries, refcnt: fd %d%s + +=item Changes to Existing Diagnostics + +=back + +=item Utility Changes + +=item Configuration and Compilation + +=item Testing + +=item Platform Support + +=over 4 + +=item Platform-Specific Notes + +Windows, MirBSD + +=back + +=item Internal Changes + +=item Selected Bug Fixes + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5139delta - what is new for perl v5.13.9 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item New regular expression modifier C</a> + +=item Any unsigned value can be encoded as a character + +=item Regular expression debugging output improvement + +=back + +=item Security + +=over 4 + +=item Restrict \p{IsUserDefined} to In\w+ and Is\w+ + +=back + +=item Incompatible Changes + +=over 4 + +=item All objects are destroyed + +=back + +=item Modules and Pragmata + +=over 4 + +=item New Modules and Pragmata + +=item Updated Modules and Pragmata + +=back + +=item Documentation + +=over 4 + +=item Changes to Existing Documentation + +=back + +=item Diagnostics + +=over 4 + +=item New Diagnostics + +=item Changes to Existing Diagnostics + +=back + +=item Utility Changes + +=item Testing + +=item Platform Support + +=over 4 + +=item Discontinued Platforms + +Apollo DomainOS, MacOS Classic + +=item Platform-Specific Notes + +Cygwin, Solaris + +=back + +=item Internal Changes + +=item Selected Bug Fixes + +=item Known Problems + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5138delta - what is new for perl v5.13.8 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item C<-d:-foo> calls C<Devel::foo::unimport> + +C<-d:-foo>, C<-d:-foo=bar> + +=item Filehandle method calls load L<IO::File> on demand + +=item Full functionality for C<use feature 'unicode_strings'> + +=item Exception Handling Backcompat Hack + +=item printf-like functions understand post-1980 size modifiers + +=item DTrace probes now include package name + +=item Stacked labels + +=back + +=item Incompatible Changes + +=over 4 + +=item C<:=> is now a syntax error + +=item Run-time code block in regular expressions + +=back + +=item Deprecations + +=over 4 + +=item C<?PATTERN?> is deprecated + +=item C<sv_compile_2op()> is now deprecated + +=item Tie functions on scalars holding typeglobs + +=back + +=item Modules and Pragmata + +=over 4 + +=item Updated Modules and Pragmata + +=item Dual-life Modules and Pragmata + +=back + +=item Diagnostics + +=over 4 + +=item New Diagnostics + +=item Changes to Existing Diagnostics + +=back + +=item Configuration and Compilation + +=item Testing + +=item Platform Support + +=over 4 + +=item Platform-Specific Notes + +NetBSD, Windows + +=back + +=item Internal Changes + +=item Selected Bug Fixes + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5137delta - what is new for perl v5.13.7 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item Single term prototype + +=item C<use re '/flags';> + +=item Statement labels can appear in more places + +=item C<use feature "unicode_strings"> now applies to more regex matching + +=item Array and hash container functions accept references + +=item y///r + +=item New global variable C<${^GLOBAL_PHASE}> + +=item Unicode Version 6.0 is now supported (mostly) + +=item Improved support for custom OPs + +=back + +=item Incompatible Changes + +=over 4 + +=item Dereferencing typeglobs + +=item Clearing stashes + +=back + +=item Deprecations + +=over 4 + +=item C<\N{BELL}> is deprecated + +=back + +=item Performance Enhancements + +=item Modules and Pragmata + +=over 4 + +=item New Modules and Pragmata + +=item Updated Modules and Pragmata + +=back + +=item Documentation + +=over 4 + +=item New Documentation + +=item Changes to Existing Documentation + +=back + +=item Diagnostics + +=over 4 + +=item New Diagnostics + +=back + +=item Utility Changes + +=item Testing + +=item Platform Support + +=over 4 + +=item Platform-Specific Notes + +Windows, VMS + +=back + +=item Internal Changes + +=item Selected Bug Fixes + +=item Obituary + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5136delta - what is new for perl v5.13.6 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item C<(?^...)> regex construct added to signify default modifiers + +=item C<"d">, C<"l">, and C<"u"> regex modifiers added + +=item C<use feature "unicode_strings"> now applies to some regex matching + +=item C<\N{...}> now handles Unicode named character sequences + +=item New function C<charnames::string_vianame()> + +=item Reentrant regular expression engine + +=item Custom per-subroutine check hooks + +=item Return value of C<delete $+{...}> + +=item C<keys>, C<values> work on arrays + +=back + +=item Incompatible Changes + +=over 4 + +=item Stringification of regexes has changed + +=item Regular expressions retain their localeness when interpolated + +=item Directory handles not copied to threads + +=item Negation treats strings differently from before + +=item Negative zero + +=back + +=item Performance Enhancements + +=item Modules and Pragmata + +=over 4 + +=item Updated Modules and Pragmata + +=back + +=item Documentation + +=over 4 + +=item Changes to Existing Documentation + +=back + +=item Diagnostics + +=over 4 + +=item Changes to Existing Diagnostics + +=back + +=item Testing + +=item Platform Support + +=over 4 + +=item Platform-Specific Notes + +IRIX, Mac OS X, OpenVOS, VMS, Windows + +=back + +=item Internal Changes + +=item Selected Bug Fixes + +=item Errata + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5135delta - what is new for perl v5.13.5 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item Adjacent pairs of nextstate opcodes are now optimized away + +=item API function to parse statements + +=item API functions for accessing the runtime hinthash + +=item C interface to C<caller()> + +=back + +=item Incompatible Changes + +=over 4 + +=item Magic variables outside the main package + +=item Smart-matching against array slices + +=item C API changes + +=back + +=item Deprecations + +=over 4 + +=item Use of qw(...) as parentheses + +=back + +=item Performance Enhancements + +=item Modules and Pragmata + +=over 4 + +=item Updated Modules and Pragmata + +C<bignum>, C<blib>, C<open>, C<threads-shared>, C<warnings> and +C<warnings::register>, C<B::Debug>, C<CPANPLUS::Dist::Build>, +C<Data::Dumper>, C<Encode>, C<Errno>, C<ExtUtils::MakeMaker>, +C<Filter::Simple>, C<Hash::Util>, C<Math::BigInt>, +C<Math::BigInt::FastCalc>, C<Math::BigRat>, C<Module::CoreList>, +C<PerlIO::scalar>, C<POSIX>, C<Safe>, C<Test::Simple>, C<Tie::Hash>, +C<Unicode::Collate>, C<XSLoader> + +=back + +=item Documentation + +=over 4 + +=item Changes to Existing Documentation + +=back + +=item Diagnostics + +=over 4 + +=item New Diagnostics + +=item Changes to Existing Diagnostics + +=back + +=item Utility Changes + +=item Testing + +=item Platform Support + +=over 4 + +=item Platform-Specific Notes + +VMS + +=back + +=item Internal Changes + +=item Selected Bug Fixes + +=item Known Problems + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5134delta - what is new for perl v5.13.4 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item C<srand()> now returns the seed + +=item C<\N{I<name>}> and C<charnames> enhancements + +=back + +=item Incompatible Changes + +=over 4 + +=item Declare API incompatibility between blead releases + +=item Check API compatibility when loading XS modules + +=item Binary Incompatible with all previous Perls + +=item Change in the parsing of certain prototypes + +=back + +=item Deprecations + +=over 4 + +=item List assignment to C<$[> + +=back + +=item Performance Enhancements + +=item Modules and Pragmata + +=over 4 + +=item New Modules and Pragmata + +=item Updated Modules and Pragmata + +C<Archive::Tar>, C<B::Lint>, C<Carp>, C<Compress::Raw::Bzip2>, +C<Compress::Raw::Zlib>, C<File::Spec>, C<I18N::Langinfo>, C<IO::Compress>, +C<Module::CoreList>, C<Test::Harness>, C<Test::Simple>, +C<Unicode::Collate>, C<feature> + +=item Removed Modules and Pragmata + +=back + +=item Documentation + +=over 4 + +=item Changes to Existing Documentation + +=back + +=item Configuration and Compilation + +=item Testing + +=item Platform Support + +=over 4 + +=item Platform-Specific Notes + +Win32 + +=back + +=item Internal Changes + +Removed C<PERL_POLLUTE>, Added C<PERL_STATIC_INLINE> + +=item Selected Bug Fixes + +=item Known Problems + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5133delta - what is new for perl v5.13.3 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item \o{...} for octals + +=item C<\N{I<name>}> and C<charnames> enhancements + +=item Uppercase X/B allowed in hexadecimal/binary literals + +=back + +=item Incompatible Changes + +=over 4 + +=item \400 - \777 + +=back + +=item Deprecations + +=over 4 + +=item Omitting a space between a regular expression and subsequent word + +=item Deprecation warning added for deprecated-in-core .pl libs + +=back + +=item Performance Enhancements + +=item Modules and Pragmata + +=over 4 + +=item Updated Modules and Pragmata + +C<autodie>, C<charnames>, C<lib>, C<threads>, C<threads::shared>, +C<warnings>, C<Archive::Extract>, C<Archive::Tar>, C<Attribute::Handlers>, +C<Compress::Raw::Bzip2>, C<Compress::Raw::Zlib>, C<Compress::Zlib>, +C<CPANPLUS>, C<Digest::MD5>, C<Digest::SHA>, C<Exporter>, +C<ExtUtils::CBuilder>, C<ExtUtils::Manifest>, C<ExtUtils::ParseXS>, +C<File::Copy>, C<I18N::LangTags>, C<IPC::Cmd>, C<IPC::SysV>, +C<Locale::Maketext>, C<Module::Build>, C<Module::CoreList>, +C<Module::Load>, C<Term::ANSIColor>, C<Test::Harness>, C<Time::HiRes>, +C<Time::Piece>, C<Unicode::Collate>, C<Unicode::Normalize> + +=back + +=item Documentation + +=over 4 + +=item New Documentation + +=item Changes to Existing Documentation + +=back + +=item Utility Changes + +=item Configuration and Compilation + +=item Testing + +=item Platform Support + +=over 4 + +=item Discontinued Platforms + +MacOS Classic + +=item Platform-Specific Notes + +Win32 + +=back + +=item Internal Changes + +=item Selected Bug Fixes + +=item Known Problems + +=item Errata + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5132delta - what is new for perl v5.13.2 + +=over 4 + +=item DESCRIPTION + +=item Incompatible Changes + +=over 4 + +=item localised tied scalars are tied again. + +=item Naming fixes in Policy_sh.SH may invalidate Policy.sh + +=item Stashes are now always defined + +=back + +=item Core Enhancements + +=over 4 + +=item Non-destructive substitution + +=item package block syntax + +=item CLONE_PARAMS structure added to ease correct thread creation + +=item perl -h no longer recommends -w + +=back + +=item Modules and Pragmata + +=over 4 + +=item Updated Modules + +release 1.94_57, bugfix: treat modules correctly that are deprecated in +perl 5.12, bugfix: RT #57482 and #57788 revealed that configure_requires +implicitly assumed build_requires instead of normal requires. (Reported by +Andrew Whatson and Father Chrysostomos respectively), testfix: solaris +should run the tests without expect because (some?) solaris have a broken +expect, testfix: run tests with cache_metadata off to prevent spill over +effects from previous test runs + +=back + +=item Changes to Existing Documentation + +=over 4 + +=item Replace wrong tr/// table in perlebcdic.pod + +=item Document tricks for user-defined casing + +=item Document $# and $* as removed and clarify $#array usage + +=item INSTALL explicitly states the requirement for C89 + +=item No longer advertise Math::TrulyRandom + +=item perlfaq synchronised to upstream + +=back + +=item Performance Enhancements + +=over 4 + +=item Multiple small improvements to threads + +=item Size optimisations to SV and HV structures + +=item Optimisation of regexp engine string comparison work + +=item Memory consumption improvements to Exporter + +=back + +=item Installation and Configuration Improvements + +=over 4 + +=item Compilation improvements + +=back + +=item Selected Bug Fixes + +Timely cleanup of SVs that are cloned into a new thread but then discovered +to be orphaned (i.e. their owners are -not- cloned) (e42956), Don't +accidentally clone lexicals in scope within active stack frames in the +parent when creating a child thread (RT #73086) (05d04d), Avoid loading +feature.pm when 'no 5.13.2;' or similar is encountered (faee19), Trap +invalid use of SvIVX on SVt_REGEXP when assertions are on (e77da3), Don't +stamp on $DB::single, $DB::trace and $DB::signal if they already have +values when $^P is assigned to (RT #72422) (4c0f30), chop now correctly +handles perl's extended UTF-8 (RT #73246) (65ab92), Defer signal handling +when shared SV locks are held to avoid deadlocks (RT #74868) (65c742), +glob() no longer crashes when %File::Glob:: is empty and CORE::GLOBAL::glob +isn't present (4984aa), perlbug now always permits the sender address to be +changed before sending - if you were having trouble sending bug reports +before now, this should fix it, we hope (e6eb90), Overloading now works +properly in conjunction with tied variables. What formerly happened was +that most ops checked their arguments for overloading I<before> checking +for magic, so for example an overloaded object returned by a tied array +access would usually be treated as not overloaded (RT #57012) (6f1401, +ed3b9b, 6a5f8c .. 24328f), Independently, a bug was fixed that prevented +$tied-E<gt>() from always calling FETCH correctly (RT #8438) (7c7501) + +=item Changed Internals + +The implementation of sv_dup_inc() has changed from a macro to a function + +=item Deprecations + =item Platform Specific Notes -Solaris, VMS, VOS +=over 4 + +=item Recent OpenBSDs now use perl's malloc + +=back =item Acknowledgements @@ -7451,7 +9246,114 @@ Solaris, VMS, VOS =back -=head2 perl5123delta, perldelta - what is new for perl v5.12.3 +=head2 perl5131delta - what is new for perl v5.13.1 + +=over 4 + +=item DESCRIPTION + +=item Incompatible Changes + +=over 4 + +=item "C<\cI<X>>" + +=item localised tied hashes, arrays and scalars are no longed tied + +=item C<given> return values + +=back + +=item Core Enhancements + +=over 4 + +=item Exception Handling Reliability + +=back + +=item Modules and Pragmata + +=over 4 + +=item Updated Modules + +C<Errno>, Perl 4 C<.pl> libraries, C<B::Deparse> + +=item Removed Modules and Pragmata + +C<Class::ISA>, C<Pod::Plainer>, C<Switch> + +=back + +=item New Documentation + +perlgpl + +=item Selected Bug Fixes + +=item Changed Internals + +=item Deprecations + +C<Perl_ptr_table_clear> + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5130delta - what is new for perl v5.13.0 + +=over 4 + +=item DESCRIPTION + +=item Core Enhancements + +=over 4 + +=item "safe signals" optimization + +=item Assignment to C<$0> sets the legacy process name with C<prctl()> on +Linux + +=item Optimization of shift; and pop; calls without arguments + +=back + +=item Modules and Pragmata + +=over 4 + +=item Updated Modules + +CGI, Data::Dumper, MIME::Base64, threads, threads-shared + +=back + +=item Installation and Configuration Improvements + +=over 4 + +=item Platform Specific Changes + +AIX + +=back + +=item Acknowledgements + +=item Reporting Bugs + +=item SEE ALSO + +=back + +=head2 perl5123delta - what is new for perl v5.12.3 =over 4 @@ -7541,7 +9443,7 @@ C<Carp>, C<CPANPLUS>, C<File::Glob>, C<File::Copy>, C<File::Spec> =back -=head2 perl5121delta, perldelta - what is new for perl v5.12.1 +=head2 perl5121delta - what is new for perl v5.12.1 =over 4 @@ -7641,7 +9543,7 @@ C<Carp>, C<CPANPLUS>, C<File::Glob>, C<File::Copy>, C<File::Spec> =item Support for C<configure_requires> in CPAN module metadata -=item C<each> is now more flexible +=item C<each>, C<keys>, C<values> are now more flexible =item C<when> as a statement modifier @@ -10539,7 +12441,7 @@ Win32::GetOSVersion =item Self-tying of Arrays and Hashes Is Forbidden -=item Variable Attributes are not Currently Usable for Tieing +=item Variable Attributes are not Currently Usable for Tying =item Building Extensions Can Fail Because Of Largefiles @@ -12045,8 +13947,6 @@ a), b), c), d), a), b), c), d) =item AUTHORS -=item DATE - =back =head2 perlamiga - Perl under Amiga OS @@ -12115,16 +14015,6 @@ B<Unix emulation for AmigaOS: ixemul.library>, B<Version of Amiga OS> =back -=head2 perlapollo, README.apollo - Perl version 5 on Apollo DomainOS - -=over 4 - -=item DESCRIPTION - -=item AUTHOR - -=back - =head2 perlbeos, README.beos - Perl version 5.8+ on BeOS =over 4 @@ -12455,8 +14345,6 @@ DJGPP, Pthreads =item $^X doesn't always contain a full path in FreeBSD -=item Perl will no longer be part of "base FreeBSD" - =back =item AUTHOR @@ -12636,10 +14524,6 @@ DJGPP, Pthreads =item Known problems -=item MacPerl - -=item Carbon - =item Cocoa =back @@ -13494,26 +15378,28 @@ utime LIST, waitpid PID,FLAGS =item DESCRIPTION +L<http://mingw.org>, L<http://mingw-w64.sf.net> + =over 4 -=item Setting Up Perl on Win32 +=item Setting Up Perl on Windows Make, Command Shell, Borland C++, Microsoft Visual C++, Microsoft Visual -C++ 2008 Express Edition, Microsoft Visual C++ 2005 Express Edition, +C++ 2008/2010 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 +MinGW release 3 with gcc =item Building -=item Testing Perl on Win32 +=item Testing Perl on Windows -=item Installation of Perl on Win32 +=item Installation of Perl on Windows -=item Usage Hints for Perl on Win32 +=item Usage Hints for Perl on Windows Environment Variables, File Globbing, Using perl from the command line, -Building Extensions, Command-line Wildcard Expansion, Win32 Specific -Extensions, Notes on 64-bit Windows +Building Extensions, Command-line Wildcard Expansion, Notes on 64-bit +Windows =item Running Perl Scripts @@ -13530,7 +15416,7 @@ Extensions, Notes on 64-bit Windows Gary Ng E<lt>71564.1743@CompuServe.COME<gt>, Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>, Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>, Jan Dubois E<lt>jand@activestate.comE<gt>, -Steve Hay E<lt>steve.hay@uk.radan.comE<gt> +Steve Hay E<lt>steve.m.hay@googlemail.comE<gt> =item SEE ALSO @@ -13540,1537 +15426,10 @@ Steve Hay E<lt>steve.hay@uk.radan.comE<gt> =head1 PRAGMA DOCUMENTATION -=head2 attributes - get/set subroutine or variable attributes - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item What C<import> does - -=item Built-in Attributes - -lvalue, method, locked - -=item Available Subroutines - -get, reftype - -=item Package-specific Attribute Handling - -FETCH_I<type>_ATTRIBUTES, MODIFY_I<type>_ATTRIBUTES - -=item Syntax of Attribute Lists - -=back - -=item EXPORTS - -=over 4 - -=item Default exports - -=item Available exports - -=item Export tags defined - -=back - -=item EXAMPLES - -=item MORE EXAMPLES - -=item SEE ALSO - -=back - -=head2 autouse::lib::autouse, autouse - postpone load of modules until a -function is used - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item WARNING - -=item AUTHOR - -=item SEE ALSO - -=back - -=head2 mro - Method Resolution Order - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item OVERVIEW - -=item The C3 MRO - -=over 4 - -=item What is C3? - -=item How does C3 work - -=back - -=item Functions - -=over 4 - -=item mro::get_linear_isa($classname[, $type]) - -=item mro::set_mro ($classname, $type) - -=item mro::get_mro($classname) - -=item mro::get_isarev($classname) - -=item mro::is_universal($classname) - -=item mro::invalidate_all_method_caches() - -=item mro::method_changed_in($classname) - -=item mro::get_pkg_gen($classname) - -=item next::method - -=item next::can - -=item maybe::next::method - -=back - -=item SEE ALSO - -=over 4 - -=item The original Dylan paper - -L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html> - -=item Pugs - -=item Parrot - -L<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>, -L<http://use.perl.org/~autrijus/journal/25768> - -=item Python 2.3 MRO related links - -L<http://www.python.org/2.3/mro.html>, -L<http://www.python.org/2.2.2/descrintro.html#mro> - -=item C3 for TinyCLOS - -L<http://www.call-with-current-continuation.org/eggs/c3.html> - -=item Class::C3 - -L<Class::C3> - -=back - -=item AUTHOR - -=back - -=head2 re - Perl pragma to alter regular expression behaviour - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item 'taint' mode - -=item 'eval' mode - -=item 'debug' mode - -=item 'Debug' mode - -Compile related options, COMPILE, PARSE, OPTIMISE, TRIEC, DUMP, Execute -related options, EXECUTE, MATCH, TRIEE, INTUIT, Extra debugging options, -EXTRA, BUFFERS, TRIEM, STATE, STACK, OPTIMISEM, OFFSETS, OFFSETSDBG, Other -useful flags, ALL, All, MORE, More - -=item Exportable Functions - -is_regexp($ref), regexp_pattern($ref), regmust($ref), regname($name,$all), -regnames($all), regnames_count() - -=back - -=item SEE ALSO - -=back - -=head2 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, No user hints defined for %s - -=item BUGS - -=over 4 - -=item autodie and string eval - -=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 autodie::hints - Provide hints about user subroutines to autodie - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Introduction - -=item What are hints? - -=item Example hints - -=back - -=item Manually setting hints from within your program - -=item Adding hints to your module - -=item Insisting on hints - -=back - -=over 4 - -=item Diagnostics - -Attempts to set_hints_for unidentifiable subroutine, fail hints cannot be -provided with either scalar or list hints for %s, %s hint missing for %s - -=item ACKNOWLEDGEMENTS - -=item AUTHOR - -=item LICENSE - -=item SEE ALSO - -=back - -=head2 autouse - postpone load of modules until a function is used - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item WARNING - -=item AUTHOR - -=item SEE ALSO - -=back - -=head2 base - Establish an ISA relationship with base classes at compile -time - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item DIAGNOSTICS - -Base class package "%s" is empty, Class 'Foo' tried to inherit from itself - -=item HISTORY - -=item CAVEATS - -=item SEE ALSO - -=back - -=head2 bigint - Transparent BigInteger support for Perl - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item use integer vs. use bigint - -=item Options - -a or accuracy, p or precision, t or trace, hex, oct, l, lib, try or only, v -or version - -=item Math Library - -=item Internal Format - -=item Sign - -=item Methods - -inf(), NaN(), e, PI, bexp(), bpi(), upgrade(), in_effect() - -=item MATH LIBRARY - -=item Caveat - -=back - -=item CAVAETS - -in_effect(), hex()/oct() - -=item MODULES USED - -=item EXAMPLES - -=item LICENSE - -=item SEE ALSO - -=item AUTHORS - -=back - -=head2 bignum - Transparent BigNumber support for Perl - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Options - -a or accuracy, p or precision, t or trace, l or lib, hex, oct, v or version - -=item Methods - -=item Caveats - -inf(), NaN(), e, PI(), bexp(), bpi(), upgrade(), in_effect() - -=item Math Library - -=item INTERNAL FORMAT - -=item SIGN - -=back - -=item CAVAETS - -in_effect(), hex()/oct() - -=item MODULES USED - -=item EXAMPLES - -=item LICENSE - -=item SEE ALSO - -=item AUTHORS - -=back - -=head2 bigrat - Transparent BigNumber/BigRational support for Perl - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Modules Used - -=item Math Library - -=item Sign - -=item Methods - -inf(), NaN(), e, PI, bexp(), bpi(), upgrade(), in_effect() - -=item MATH LIBRARY - -=item Cavaet - -=item Options - -a or accuracy, p or precision, t or trace, l or lib, hex, oct, v or version - -=back - -=item CAVAETS - -in_effect(), hex()/oct() - -=item EXAMPLES - - perl -Mbigrat -le 'print sqrt(33)' - perl -Mbigrat -le 'print 2*255' - perl -Mbigrat -le 'print 4.5+2*255' - perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3' - perl -Mbigrat -le 'print 12->is_odd()'; - perl -Mbignum=l,GMP -le 'print 7 ** 7777' - -=item LICENSE - -=item SEE ALSO - -=item AUTHORS - -=back - -=head2 blib - Use MakeMaker's uninstalled version of a package - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item BUGS - -=item AUTHOR - -=back - -=head2 bytes - Perl pragma to force byte semantics rather than character -semantics - -=over 4 - -=item NOTICE - -=item SYNOPSIS - -=item DESCRIPTION - -=item LIMITATIONS - -=item SEE ALSO - -=back - -=head2 charnames - define character names for C<\N{named}> string literal -escapes - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item ALIASES - -=item CUSTOM ALIASES - -=over 4 - -=item Anonymous hashes - -=item Alias file - -=item Alias shortcut - -=back - -=item charnames::viacode(code) - -=item charnames::vianame(name) - -=item CUSTOM TRANSLATORS - -=item ILLEGAL CHARACTERS - -=item BUGS - -=back - -=head2 constant - Perl pragma to declare constants - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item NOTES - -=over 4 - -=item List constants - -=item Defining multiple constants at once - -=item Magic constants - -=back - -=item TECHNICAL NOTES - -=item CAVEATS - -=item SEE ALSO - -=item BUGS - -=item AUTHORS - -=item COPYRIGHT & LICENSE - -=back - -=head2 deprecate - Perl pragma for deprecating the core version of a module - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item EXPORT - -=back - -=item SEE ALSO - -=item AUTHOR - -=item COPYRIGHT AND LICENSE - -=back - -=head2 diagnostics, splain - produce verbose warning diagnostics - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item The C<diagnostics> Pragma - -=item The I<splain> Program - -=back - -=item EXAMPLES - -=item INTERNALS - -=item BUGS - -=item AUTHOR - -=back - -=head2 encoding - allows you to write your script in non-ascii or non-utf8 - -=over 4 - -=item SYNOPSIS - -=item ABSTRACT - -=over 4 - -=item Literal Conversions - -=item PerlIO layers for C<STD(IN|OUT)> - -=item Implicit upgrading for byte strings - -=item Side effects - -=back - -=item FEATURES THAT REQUIRE 5.8.1 - -"NON-EUC" doublebyte encodings, tr//, DATA pseudo-filehandle - -=item USAGE - -use encoding [I<ENCNAME>] ;, use encoding I<ENCNAME> [ STDIN =E<gt> -I<ENCNAME_IN> ...] ;, use encoding I<ENCNAME> Filter=E<gt>1;, no encoding; - -=item The Filter Option - -=over 4 - -=item Filter-related changes at Encode version 1.87 - -=back - -=item CAVEATS - -=over 4 - -=item NOT SCOPED - -=item DO NOT MIX MULTIPLE ENCODINGS - -=item tr/// with ranges - -Legend of characters above - -=back - -=item EXAMPLE - Greekperl - -=item KNOWN PROBLEMS - -literals in regex that are longer than 127 bytes, EBCDIC, format, Thread -safety - -=over 4 - -=item The Logic of :locale - -=back - -=item HISTORY - -=item SEE ALSO - -=back - -=head2 encoding::warnings - Warn on implicit encoding conversions - -=over 4 - -=item VERSION - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Overview of the problem - -=item Detecting the problem - -=item Solving the problem - -Upgrade both sides to unicode-strings, Downgrade both sides to -byte-strings, Specify the encoding for implicit byte-string upgrading, -PerlIO layers for B<STDIN> and B<STDOUT>, Literal conversions, Implicit -upgrading for byte-strings - -=back - -=item CAVEATS - -=back - -=over 4 - -=item SEE ALSO - -=item AUTHORS - -=item COPYRIGHT - -=back - -=head2 feature - Perl pragma to enable new features - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Lexical effect - -=item C<no feature> - -=item The 'switch' feature - -=item The 'say' feature - -=item the 'state' feature - -=item the 'unicode_strings' feature - -=back - -=item FEATURE BUNDLES - -=item IMPLICIT LOADING - -=back - -=head2 fields - compile-time class fields - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -new, phash - -=item SEE ALSO - -=back - -=head2 filetest - Perl pragma to control the filetest permission operators - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Consider this carefully - -=item The "access" sub-pragma - -=item Limitation with regard to C<_> - -=back - -=back - -=head2 if - C<use> a Perl module if a condition holds - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item BUGS - -=item AUTHOR - -=back - -=head2 inc::latest - use modules bundled in inc/ if they are newer than -installed ones - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Special notes on bundling - -=back - -=item USAGE - -=over 4 - -=item Author-mode - -loaded_modules(), write(), bundle_module() - -=item As bundled in inc/ - -=back - -=item AUTHOR - -=item COPYRIGHT - -=item SEE ALSO - -=back - -=head2 integer - Perl pragma to use integer arithmetic instead of floating -point - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=back - -=head2 less - perl pragma to request less of something - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item FOR MODULE AUTHORS - -=over 4 - -=item C<< BOOLEAN = less->of( FEATURE ) >> - -=item C<< FEATURES = less->of() >> - -=back - -=item CAVEATS - -This probably does nothing, This works only on 5.10+ - -=back - -=head2 lib - manipulate @INC at compile time - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Adding directories to @INC - -=item Deleting directories from @INC - -=item Restoring original @INC - -=back - -=item CAVEATS - -=item NOTES - -=item SEE ALSO - -=item AUTHOR - -=item COPYRIGHT AND LICENSE - -=back - -=head2 locale - Perl pragma to use and avoid POSIX locales for built-in -operations - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=back - -=head2 open - perl pragma to set default PerlIO layers for input and output - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item NONPERLIO FUNCTIONALITY - -=item IMPLEMENTATION DETAILS - -=item SEE ALSO - -=back - -=head2 ops - Perl pragma to restrict unsafe operations when compiling - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item SEE ALSO - -=back - -=head2 overload - Package for overloading Perl operations - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Declaration of overloaded functions - -=item Calling Conventions for Binary Operations - -FALSE, TRUE, C<undef> - -=item Calling Conventions for Unary Operations - -=item Calling Conventions for Mutators - -C<++> and C<-->, C<x=> and other assignment versions - -=item Overloadable Operations - -I<Arithmetic operations>, I<Comparison operations>, I<Bit operations>, -I<Increment and decrement>, I<Transcendental functions>, I<Boolean, string, -numeric and regexp conversions>, I<Iteration>, I<File tests>, I<Matching>, -I<Dereferencing>, I<Special> - -=item Inheritance and overloading - -Strings as values of C<use overload> directive, Overloading of an operation -is inherited by derived classes - -=back - -=item SPECIAL SYMBOLS FOR C<use overload> - -=over 4 - -=item Last Resort - -=item Fallback - -C<undef>, TRUE, defined, but FALSE - -=item Copy Constructor - -B<Example> - -=back - -=item MAGIC AUTOGENERATION - -I<Assignment forms of arithmetic operations>, I<Conversion operations>, -I<Increment and decrement>, C<abs($a)>, I<Unary minus>, I<Negation>, -I<Concatenation>, I<Comparison operations>, I<Iterator>, I<Dereferencing>, -I<Copy operator> - -=item Minimal set of overloaded operations - -=item Losing overloading - -=item Run-time Overloading - -=item Public functions - -overload::StrVal(arg), overload::Overloaded(arg), overload::Method(obj,op) - -=item Overloading constants - -integer, float, binary, q, qr - -=item IMPLEMENTATION - -=item Metaphor clash - -=item Cookbook - -=over 4 - -=item Two-face scalars - -=item Two-face references - -=item Symbolic calculator - -=item I<Really> symbolic calculator - -=back - -=item AUTHOR - -=item SEE ALSO - -=item DIAGNOSTICS - -Odd number of arguments for overload::constant, `%s' is not an overloadable -type, `%s' is not a code reference - -=item BUGS - -=back - -=head2 overloading - perl pragma to lexically control overloading - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -C<no overloading>, C<no overloading @ops>, C<use overloading>, C<use -overloading @ops> - -=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 - -=item SYNOPSIS - -=item DESCRIPTION - -=item OPTIONS - -=over 4 - -=item SIGNAL HANDLERS - -B<stack-trace>, B<die>, B<handler> I<your-handler> - -=item SIGNAL LISTS - -B<normal-signals>, B<error-signals>, B<old-interface-signals> - -=item OTHER - -B<untrapped>, B<any>, I<signal>, I<number> - -=back - -=item EXAMPLES - -=back - -=head2 sort - perl pragma to control sort() behaviour - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item CAVEATS - -=back - -=head2 strict - Perl pragma to restrict unsafe constructs - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -C<strict refs>, C<strict vars>, C<strict subs> - -=item HISTORY - -=back - -=head2 subs - Perl pragma to predeclare sub names - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=back - -=head2 threads - Perl interpreter-based threads - -=over 4 - -=item VERSION - -=item SYNOPSIS - -=item DESCRIPTION - -$thr = threads->create(FUNCTION, ARGS), $thr->join(), $thr->detach(), -threads->detach(), threads->self(), $thr->tid(), threads->tid(), "$thr", -threads->object($tid), threads->yield(), threads->list(), -threads->list(threads::all), threads->list(threads::running), -threads->list(threads::joinable), $thr1->equal($thr2), async BLOCK;, -$thr->error(), $thr->_handle(), threads->_handle() - -=item EXITING A THREAD - -threads->exit(), threads->exit(status), die(), exit(status), use threads -'exit' => 'threads_only', threads->create({'exit' => 'thread_only'}, ...), -$thr->set_thread_exit_only(boolean), threads->set_thread_exit_only(boolean) - -=item THREAD STATE - -$thr->is_running(), $thr->is_joinable(), $thr->is_detached(), -threads->is_detached() - -=item THREAD CONTEXT - -=over 4 - -=item Explicit context - -=item Implicit context - -=item $thr->wantarray() - -=item threads->wantarray() - -=back - -=item THREAD STACK SIZE - -threads->get_stack_size();, $size = $thr->get_stack_size();, $old_size = -threads->set_stack_size($new_size);, use threads ('stack_size' => VALUE);, -$ENV{'PERL5_ITHREADS_STACK_SIZE'}, threads->create({'stack_size' => VALUE}, -FUNCTION, ARGS), $thr2 = $thr1->create(FUNCTION, ARGS) - -=item THREAD SIGNALLING - -$thr->kill('SIG...'); - -=item WARNINGS - -Perl exited with active threads:, Thread creation failed: pthread_create -returned #, Thread # terminated abnormally: .., Using minimum thread stack -size of #, Thread creation failed: pthread_attr_setstacksize(I<SIZE>) -returned 22 - -=item ERRORS - -This Perl not built to support threads, Cannot change stack size of an -existing thread, Cannot signal threads without safe signals, Unrecognized -signal name: .. - -=item BUGS AND LIMITATIONS - -Thread-safe modules, Using non-thread-safe modules, Current working -directory, Environment variables, Parent-child threads, Creating threads -inside special blocks, Unsafe signals, Perl has been built with -C<PERL_OLD_SIGNALS> (see C<perl -V>), The environment variable -C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">), The -module L<Perl::Unsafe::Signals> is used, Returning closures from threads, -Returning objects from threads, END blocks in threads, Perl Bugs and the -CPAN Version of L<threads> - -=item REQUIREMENTS - -=item SEE ALSO - -=item AUTHOR - -=item LICENSE - -=item ACKNOWLEDGEMENTS - -=back - -=head2 threadshared, threads::shared - Perl extension for sharing data -structures between threads - -=over 4 - -=item VERSION - -=item SYNOPSIS - -=item DESCRIPTION - -=item EXPORT - -=item FUNCTIONS - -share VARIABLE, 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 - -=item NOTES - -=item BUGS AND LIMITATIONS - -=item SEE ALSO - -=item AUTHOR - -=item LICENSE - -=back - -=head2 utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source -code - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Utility functions - -$num_octets = utf8::upgrade($string), $success = utf8::downgrade($string[, -FAIL_OK]), utf8::encode($string), $success = utf8::decode($string), $flag = -utf8::is_utf8(STRING), $flag = utf8::valid(STRING) - -=back - -=item BUGS - -=item SEE ALSO - -=back - -=head2 vars - Perl pragma to predeclare global variable names (obsolete) - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=back - -=head2 version - Perl extension for Version Objects - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item TYPES OF VERSION OBJECTS - -Decimal Versions, Dotted Decimal Versions - -=item DECLARING VERSIONS - -=over 4 - -=item How to convert a module from decimal to dotted-decimal - -=item How to C<declare()> a dotted-decimal version - -=back - -=item PARSING AND COMPARING VERSIONS - -=over 4 - -=item How to C<parse()> a version - -=item How to check for a legal version string - -C<is_lax()>, C<is_strict()> - -=item How to compare version objects - -=back - -=item OBJECT METHODS - -=over 4 - -=item is_alpha() - -=item is_qv() - -=item normal() - -=item numify() - -=item stringify() - -=back - -=item EXPORTED FUNCTIONS - -=over 4 - -=item qv() - -=item is_lax() - -=item is_strict() - -=back - -=item AUTHOR - -=item SEE ALSO - -=back - -=head2 version::Internals - Perl extension for Version Objects - -=over 4 - -=item DESCRIPTION - -=item WHAT IS A VERSION? - -Decimal Versions, Dotted-Decimal Versions - -=over 4 - -=item Decimal Versions - -=item Dotted-Decimal Versions - -=item Alpha Versions - -=item Regular Expressions for Version Parsing - -C<$version::LAX>, C<$version::STRICT>, v1.234.5 - -=back - -=item IMPLEMENTATION DETAILS - -=over 4 - -=item Equivalence between Decimal and Dotted-Decimal Versions - -=item Quoting Rules - -=item What about v-strings? - -=item Version Object Internals - -original, qv, alpha, version - -=item Replacement UNIVERSAL::VERSION - -=back - -=item USAGE DETAILS - -=over 4 - -=item Using modules that use version.pm - -Decimal versions always work, Dotted-Decimal version work sometimes - -=item Object Methods - -new(), qv(), Normal Form, Numification, Stringification, Comparison -operators, Logical Operators - -=back - -=item AUTHOR - -=item SEE ALSO - -=back - -=head2 vmsish - Perl pragma to control VMS-specific language features - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -C<vmsish status>, C<vmsish exit>, C<vmsish time>, C<vmsish hushed> - -=back - -=head2 warnings - Perl pragma to control optional warnings - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -use warnings::register, warnings::enabled(), warnings::enabled($category), -warnings::enabled($object), warnings::fatal_enabled(), -warnings::fatal_enabled($category), warnings::fatal_enabled($object), -warnings::warn($message), warnings::warn($category, $message), -warnings::warn($object, $message), warnings::warnif($message), -warnings::warnif($category, $message), warnings::warnif($object, $message) - -=back - -=head2 warnings::register - warnings import function - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=back - =head1 MODULE DOCUMENTATION -=head2 AnyDBM_File - provide framework for multiple DBMs +=head2 C:\perl_tl\perl-5.14.2\lib::AnyDBM_File, AnyDBM_File - provide +framework for multiple DBMs =over 4 @@ -15090,7 +15449,8 @@ warnings::warnif($category, $message), warnings::warnif($object, $message) =back -=head2 App::Cpan - easily interact with CPAN from the command line +=head2 C:\perl_tl\perl-5.14.2\lib::App::Cpan, App::Cpan - easily interact +with CPAN from the command line =over 4 @@ -15137,7 +15497,8 @@ run() =back -=head2 App::Prove - Implements the C<prove> command. +=head2 C:\perl_tl\perl-5.14.2\lib::App::Prove, App::Prove - Implements the +C<prove> command. =over 4 @@ -15170,12 +15531,13 @@ run() =item Attributes C<archive>, C<argv>, C<backwards>, C<blib>, C<color>, C<directives>, -C<dry>, C<exec>, C<extension>, C<failures>, C<comments>, C<formatter>, +C<dry>, C<exec>, C<extensions>, C<failures>, C<comments>, 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<state_class>, C<taint_fail>, C<taint_warn>, -C<test_args>, C<timer>, C<verbose>, C<warnings_fail>, C<warnings_warn> +C<test_args>, C<timer>, C<verbose>, C<warnings_fail>, C<warnings_warn>, +C<tapversion>, C<trap> =back @@ -15193,7 +15555,8 @@ 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. +=head2 C:\perl_tl\perl-5.14.2\lib::App::Prove::State, App::Prove::State - +State storage for the C<prove> command. =over 4 @@ -15217,7 +15580,7 @@ C<test_args>, C<timer>, C<verbose>, C<warnings_fail>, C<warnings_warn> =item Class Methods -C<store>, C<extension> (optional), C<result_class> (optional) +C<store>, C<extensions> (optional), C<result_class> (optional) =back @@ -15231,7 +15594,7 @@ C<store>, C<extension> (optional), C<result_class> (optional) =over 4 -=item C<extension> +=item C<extensions> =back @@ -15256,7 +15619,8 @@ C<new>, C<old>, C<save> =back -=head2 App::Prove::State::Result - Individual test suite results. +=head2 C:\perl_tl\perl-5.14.2\lib::App::Prove::State::Result, +App::Prove::State::Result - Individual test suite results. =over 4 @@ -15296,7 +15660,8 @@ C<new>, C<old>, C<save> =back -=head2 App::Prove::State::Result::Test - Individual test results. +=head2 C:\perl_tl\perl-5.14.2\lib::App::Prove::State::Result::Test, +App::Prove::State::Result::Test - Individual test results. =over 4 @@ -15330,7 +15695,8 @@ C<new>, C<old>, C<save> =back -=head2 Archive::Extract - A generic archive extracting mechanism +=head2 C:\perl_tl\perl-5.14.2\lib::Archive::Extract, Archive::Extract - A +generic archive extracting mechanism =over 4 @@ -15349,7 +15715,7 @@ C<new>, C<old>, C<save> =item $ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE]) -tar, tgz, gz, Z, zip, bz2, tbz, lzma +tar, tgz, gz, Z, zip, bz2, tbz, lzma, xz, txz =back @@ -15399,6 +15765,8 @@ $ae->extract_path, $ae->files =item $ae->is_lzma +=item $ae->is_xz + =back =over 4 @@ -15411,6 +15779,8 @@ $ae->extract_path, $ae->files =item $ae->bin_unlzma +=item $ae->bin_unxz + =back =over 4 @@ -15421,6 +15791,12 @@ $ae->extract_path, $ae->files =over 4 +=item debug( MESSAGE ) + +=back + +=over 4 + =item HOW IT WORKS =item CAVEATS @@ -15459,7 +15835,8 @@ Mime magic support, Thread safety =back -=head2 Archive::Tar - module for manipulations of tar archives +=head2 C:\perl_tl\perl-5.14.2\lib::Archive::Tar, Archive::Tar - module for +manipulations of tar archives =over 4 @@ -15665,6 +16042,8 @@ FILE, HARDLINK, SYMLINK, CHARDEV, BLOCKDEV, DIR, FIFO, SOCKET =item $Archive::Tar::HAS_IO_STRING +=item $Archive::Tar::ZERO_PAD_NUMBERS + =back =item FAQ @@ -15687,8 +16066,8 @@ compressed archive =item SEE ALSO -The GNU tar specification, The PAX format specication, A comparison of GNU -and POSIX tar standards; +The GNU tar specification, The PAX format specification, A comparison of +GNU and POSIX tar standards; C<http://www.delorie.com/gnu/docs/tar/tar_114.html>, GNU tar intends to switch to POSIX compatibility, A Comparison between various tar implementations @@ -15701,8 +16080,8 @@ implementations =back -=head2 Archive::Tar::File - a subclass for in-memory extracted file from -Archive::Tar +=head2 C:\perl_tl\perl-5.14.2\lib::Archive::Tar::File, Archive::Tar::File - +a subclass for in-memory extracted file from Archive::Tar =over 4 @@ -15791,7 +16170,8 @@ $file->is_longlink, $file->is_label, $file->is_unknown =back -=head2 Attribute::Handlers - Simpler definition of attribute handlers +=head2 C:\perl_tl\perl-5.14.2\lib::Attribute::Handlers, Attribute::Handlers +- Simpler definition of attribute handlers =over 4 @@ -15839,7 +16219,8 @@ be able to apply END handler> =back -=head2 AutoLoader - load subroutines only on demand +=head2 C:\perl_tl\perl-5.14.2\lib::AutoLoader, AutoLoader - load +subroutines only on demand =over 4 @@ -15873,7 +16254,8 @@ be able to apply END handler> =back -=head2 AutoSplit - split a package for autoloading +=head2 C:\perl_tl\perl-5.14.2\lib::AutoSplit, AutoSplit - split a package +for autoloading =over 4 @@ -15897,7 +16279,7 @@ $keep, $check, $modtime =back -=head2 B - The Perl Compiler Backend +=head2 C:\perl_tl\perl-5.14.2\lib::B, B - The Perl Compiler Backend =over 4 @@ -15930,7 +16312,7 @@ main_root, main_start, walkoptree(OP, METHOD), walkoptree_debug(DEBUG) ppname(OPNUM), hash(STR), cast_I32(I), minus_c, cstring(STR), perlstring(STR), class(OBJ), threadsv_names -=item Exported utility variabiles +=item Exported utility variables @optype, @specialsv_name @@ -16025,8 +16407,7 @@ children =item B::PMOP Methods -pmreplroot, pmreplstart, pmnext, pmregexp, pmflags, extflags, precomp, -pmoffset +pmreplroot, pmreplstart, pmnext, pmflags, extflags, precomp, pmoffset =item B::SVOP METHOD @@ -16055,7 +16436,8 @@ hints_hash =back -=head2 B::Concise - Walk Perl syntax tree, printing concise info about ops +=head2 C:\perl_tl\perl-5.14.2\lib::B::Concise, B::Concise - Walk Perl +syntax tree, printing concise info about ops =over 4 @@ -16160,7 +16542,8 @@ a{_POSIX_SAVED_IDS}', perl -MB::Concise -e =back -=head2 B::Debug - Walk Perl syntax tree, printing debug info about ops +=head2 C:\perl_tl\perl-5.14.2\lib::B::Debug, B::Debug - Walk Perl syntax +tree, printing debug info about ops =over 4 @@ -16170,15 +16553,14 @@ a{_POSIX_SAVED_IDS}', perl -MB::Concise -e =item OPTIONS -=item Changes - =item AUTHOR =item LICENSE =back -=head2 B::Deparse - Perl compiler backend to produce perl code +=head2 C:\perl_tl\perl-5.14.2\lib::B::Deparse, B::Deparse - Perl compiler +backend to produce perl code =over 4 @@ -16216,7 +16598,7 @@ strict, $[, bytes, utf8, integer, re, warnings, hint_bits, warning_bits, =back -=head2 B::Lint - Perl lint +=head2 C:\perl_tl\perl-5.14.2\lib::B::Lint, B::Lint - Perl lint =over 4 @@ -16249,33 +16631,17 @@ validate against older perls =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 +=head2 C:\perl_tl\perl-5.14.2\lib::B::Lint::Debug, B::Lint::Debug - Adds +debugging stringification to B:: =over 4 -=item SYNOPSIS - =item DESCRIPTION -=item CONVENTIONS - -=item IMPLEMENTATION - -=item BUGS - -=item AUTHOR - =back -=head2 B::Showlex - Show lexical variables used in functions or files +=head2 C:\perl_tl\perl-5.14.2\lib::B::Showlex, B::Showlex - Show lexical +variables used in functions or files =over 4 @@ -16299,7 +16665,8 @@ validate against older perls =back -=head2 B::Terse - Walk Perl syntax tree, printing terse info about ops +=head2 C:\perl_tl\perl-5.14.2\lib::B::Terse, B::Terse - Walk Perl syntax +tree, printing terse info about ops =over 4 @@ -16311,7 +16678,8 @@ validate against older perls =back -=head2 B::Xref - Generates cross reference reports for Perl programs +=head2 C:\perl_tl\perl-5.14.2\lib::B::Xref, B::Xref - Generates cross +reference reports for Perl programs =over 4 @@ -16329,7 +16697,8 @@ C<-oFILENAME>, C<-r>, C<-d>, C<-D[tO]> =back -=head2 Benchmark - benchmark running times of Perl code +=head2 C:\perl_tl\perl-5.14.2\lib::Benchmark, Benchmark - benchmark running +times of Perl code =over 4 @@ -16375,7 +16744,8 @@ disablecache ( ), enablecache ( ), timesum ( T1, T2 ) =back -=head2 CGI - Handle Common Gateway Interface requests and responses +=head2 C:\perl_tl\perl-5.14.2\lib::CGI, CGI - Handle Common Gateway +Interface requests and responses =over 4 @@ -16585,7 +16955,7 @@ B<onBlur>, B<onSelect>, B<onMouseOver>, B<onMouseOut> B<Accept()>, B<raw_cookie()>, B<user_agent()>, B<path_info()>, B<path_translated()>, B<remote_host()>, B<remote_addr()>, B<script_name()> -Return the script name as a partial URL, for self-refering scripts, +Return the script name as a partial URL, for self-referring scripts, B<referer()>, B<auth_type ()>, B<server_name ()>, B<virtual_host ()>, B<server_port ()>, B<virtual_port ()>, B<server_software ()>, B<remote_user ()>, B<user_name ()>, B<request_method()>, B<content_type()>, B<http()>, @@ -16607,6 +16977,14 @@ basis>, B<2. Globally for all scripts> =item COMPATIBILITY WITH CGI-LIB.PL +=over 4 + +=item Cgi-lib functions that are available in CGI.pm + +=item Cgi-lib functions that are not available in CGI.pm + +=back + =item AUTHOR INFORMATION =item CREDITS @@ -16632,7 +17010,8 @@ MacEachern (dougm@opengroup.org), Robin Houston (robin@oneworld.org), =back -=head2 CGI::Apache - Backward compatibility module for CGI.pm +=head2 C:\perl_tl\perl-5.14.2\lib::CGI::Apache, CGI::Apache - Backward +compatibility module for CGI.pm =over 4 @@ -16650,8 +17029,8 @@ MacEachern (dougm@opengroup.org), Robin Houston (robin@oneworld.org), =back -=head2 CGI::Carp, B<CGI::Carp> - CGI routines for writing to the HTTPD (or -other) error log +=head2 C:\perl_tl\perl-5.14.2\lib::CGI::Carp, B<CGI::Carp> - CGI routines +for writing to the HTTPD (or other) error log =over 4 @@ -16671,6 +17050,12 @@ other) error log =item DOING MORE THAN PRINTING A MESSAGE IN THE EVENT OF PERL ERRORS +=over 4 + +=item SUPPRESSING PERL ERRORS APPEARING IN THE BROWSER WINDOW + +=back + =item MAKING WARNINGS APPEAR AS HTML COMMENTS =item OVERRIDING THE NAME OF THE PROGRAM @@ -16681,7 +17066,8 @@ other) error log =back -=head2 CGI::Cookie - Interface to Netscape Cookies +=head2 C:\perl_tl\perl-5.14.2\lib::CGI::Cookie, CGI::Cookie - Interface to +HTTP Cookies =over 4 @@ -16691,7 +17077,7 @@ other) error log =item USING CGI::Cookie -B<1. expiration date>, B<2. domain>, B<3. path>, B<4. secure flag>, B<4. +B<1. expiration date>, B<2. domain>, B<3. path>, B<4. secure flag>, B<5. httponly flag> =over 4 @@ -16716,7 +17102,8 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()> =back -=head2 CGI::Fast - CGI Interface for Fast CGI +=head2 C:\perl_tl\perl-5.14.2\lib::CGI::Fast, CGI::Fast - CGI Interface for +Fast CGI =over 4 @@ -16746,7 +17133,8 @@ FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE =back -=head2 CGI::Pretty - module to produce nicely formatted HTML code +=head2 C:\perl_tl\perl-5.14.2\lib::CGI::Pretty, CGI::Pretty - module to +produce nicely formatted HTML code =over 4 @@ -16770,7 +17158,8 @@ FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE =back -=head2 CGI::Push - Simple Interface to Server Push +=head2 C:\perl_tl\perl-5.14.2\lib::CGI::Push, CGI::Push - Simple Interface +to Server Push =over 4 @@ -16800,7 +17189,8 @@ FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE =back -=head2 CGI::Switch - Backward compatibility module for defunct CGI::Switch +=head2 C:\perl_tl\perl-5.14.2\lib::CGI::Switch, CGI::Switch - Backward +compatibility module for defunct CGI::Switch =over 4 @@ -16818,7 +17208,8 @@ FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE =back -=head2 CGI::Util - Internal utilities used by CGI module +=head2 C:\perl_tl\perl-5.14.2\lib::CGI::Util, CGI::Util - Internal +utilities used by CGI module =over 4 @@ -16832,7 +17223,8 @@ FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE =back -=head2 CORE - Pseudo-namespace for Perl's core routines +=head2 C:\perl_tl\perl-5.14.2\lib::CORE, CORE - Pseudo-namespace for Perl's +core routines =over 4 @@ -16848,7 +17240,8 @@ FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE =back -=head2 CPAN - query, download and build perl modules from CPAN sites +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN, CPAN - query, download and build +perl modules from CPAN sites =over 4 @@ -17053,6 +17446,8 @@ http firewall, ftp firewall, One-way visibility, SOCKS, IP Masquerade =item CPANPLUS +=item CPANMINUS + =back =item SECURITY ADVICE @@ -17069,7 +17464,8 @@ http firewall, ftp firewall, One-way visibility, SOCKS, IP Masquerade =back -=head2 CPAN::API::HOWTO - a recipe book for programming with CPAN.pm +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::API::HOWTO, CPAN::API::HOWTO - a +recipe book for programming with CPAN.pm =over 4 @@ -17091,7 +17487,8 @@ http firewall, ftp firewall, One-way visibility, SOCKS, IP Masquerade =back -=head2 CPAN::Distroprefs -- read and match distroprefs +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Distroprefs, CPAN::Distroprefs -- +read and match distroprefs =over 4 @@ -17122,7 +17519,8 @@ files remain to be found =back -=head2 CPAN::FirstTime - Utility for CPAN::Config file Initialization +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::FirstTime, CPAN::FirstTime - +Utility for CPAN::Config file Initialization =over 4 @@ -17144,8 +17542,8 @@ 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, version_timeout, -yaml_load_code, yaml_module +perl5lib_verbosity, prefer_external_tar, trust_test_report_history, +use_sqlite, version_timeout, yaml_load_code, yaml_module =over 4 @@ -17153,7 +17551,8 @@ yaml_load_code, yaml_module =back -=head2 CPAN::Kwalify - Interface between CPAN.pm and Kwalify.pm +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Kwalify, CPAN::Kwalify - Interface +between CPAN.pm and Kwalify.pm =over 4 @@ -17169,7 +17568,377 @@ _validate($schema_name, $data, $file, $doc), yaml($schema_name) =back -=head2 CPAN::Version - utility functions to compare CPAN versions +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Meta, CPAN::Meta - the +distribution metadata for a CPAN dist + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item new + +=item create + +=item load_file + +=item load_yaml_string + +=item load_json_string + +=item save + +=item meta_spec_version + +=item effective_prereqs + +=item should_index_file + +=item should_index_package + +=item features + +=item feature + +=item as_struct + +=item as_string + +=back + +=item STRING DATA + +=item LIST DATA + +=item MAP DATA + +=item CUSTOM DATA + +=item BUGS + +=item SEE ALSO + +=item AUTHORS + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Meta::Converter, +CPAN::Meta::Converter - Convert CPAN distribution metadata structures + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item new + +=item convert + +=back + +=item BUGS + +=item AUTHORS + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Meta::Feature, CPAN::Meta::Feature +- an optional feature provided by a CPAN distribution + +=over 4 + +=item VERSION + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item new + +=item identifier + +=item description + +=item prereqs + +=back + +=item BUGS + +=item AUTHORS + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Meta::History, CPAN::Meta::History +- history of CPAN Meta Spec changes + +=over 4 + +=item VERSION + +=item DESCRIPTION + +=item HISTORY + +=over 4 + +=item Version 2 + +=item Version 1.4 + +=item Version 1.3 + +=item Version 1.2 + +=item Version 1.1 + +=item Version 1.0 + +=back + +=item AUTHORS + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Meta::Prereqs, CPAN::Meta::Prereqs +- a set of distribution prerequisites by phase and type + +=over 4 + +=item VERSION + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item new + +=item requirements_for + +=item with_merged_prereqs + +=item as_string_hash + +=item is_finalized + +=item finalize + +=item clone + +=back + +=item BUGS + +=item AUTHORS + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Meta::Spec, CPAN::Meta::Spec - +specification for CPAN distribution metadata + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item TERMINOLOGY + +distribution, module, package, consumer, producer, must, should, may, etc + +=item DATA TYPES + +=over 4 + +=item Boolean + +=item String + +=item List + +=item Map + +=item License String + +=item URL + +=item Version + +=item Version Range + +=back + +=item STRUCTURE + +=over 4 + +=item REQUIRED FIELDS + +version, url, stable, testing, unstable + +=item OPTIONAL FIELDS + +file, directory, package, namespace, description, prereqs, file, version, +homepage, license, bugtracker, repository + +=item DEPRECATED FIELDS + +=back + +=item VERSION NUMBERS + +=over 4 + +=item Version Formats + +Decimal versions, Dotted-integer versions + +=item Version Ranges + +=back + +=item PREREQUISITES + +=over 4 + +=item Prereq Spec + +configure, build, test, runtime, develop, requires, recommends, suggests, +conflicts + +=item Merging and Resolving Prerequisites + +=back + +=item SERIALIZATION + +=item NOTES FOR IMPLEMENTORS + +=over 4 + +=item Extracting Version Numbers from Perl Modules + +=item Comparing Version Numbers + +=back + +=item SEE ALSO + +=item CONTRIBUTORS + +=item AUTHORS + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Meta::Validator, +CPAN::Meta::Validator - validate CPAN distribution metadata structures + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item new + +=item is_valid + +=item errors + +=item Check Methods + +check_map($spec,$data) + +=item Validator Methods + +header($self,$key,$value) + +=back + +=item BUGS + +=item AUTHORS + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Meta::YAML, CPAN::Meta::YAML - +Read and write a subset of YAML for CPAN Meta files + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item SUPPORT + +=item SEE ALSO + +=item AUTHORS + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Nox, CPAN::Nox - Wrapper around +CPAN.pm without using any XS module + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item LICENSE + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::CPAN::Version, CPAN::Version - utility +functions to compare CPAN versions =over 4 @@ -17181,12 +17950,15 @@ _validate($schema_name, $data, $file, $doc), yaml($schema_name) =back -=head2 CPANPLUS - API & CLI access to the CPAN mirrors +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS, CPANPLUS - API & CLI access to +the CPAN mirrors =over 4 =item SYNOPSIS +=item DESCRIPTION + =item GUIDE TO DOCUMENTATION =over 4 @@ -17207,8 +17979,16 @@ _validate($schema_name, $data, $file, $doc), yaml($schema_name) =item STARTING AN INTERACTIVE SHELL +=item CHOOSE A SHELL + =item BUILDING PACKAGES +=back + +=item FUNCTIONS + +=over 4 + =item $bool = install( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz ) =item $where = fetch( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz ) @@ -17236,7 +18016,7 @@ I<cpanplus-devel@lists.sourceforge.net> =back -=head2 CPANPLUS::Backend +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Backend, CPANPLUS::Backend =over 4 @@ -17413,7 +18193,8 @@ BOOL] ); =back -=head2 CPANPLUS::Backend::RV +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Backend::RV, +CPANPLUS::Backend::RV =over 4 @@ -17444,7 +18225,7 @@ ok, args, rv, function =back -=head2 CPANPLUS::Config +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Config, CPANPLUS::Config =over 4 @@ -17548,7 +18329,7 @@ perlwrapper =back -=head2 CPANPLUS::Configure +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Configure, CPANPLUS::Configure =over 4 @@ -17623,7 +18404,7 @@ _set|_get_mirror, _set|_get_fetch =back -=head2 CPANPLUS::Dist +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Dist, CPANPLUS::Dist =over 4 @@ -17685,15 +18466,19 @@ $version_spec ) =back -=head2 CPANPLUS::Dist::Autobundle +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Dist::Autobundle, +CPANPLUS::Dist::Autobundle =over 4 =item SYNOPSIS +=item DESCRIPTION + =back -=head2 CPANPLUS::Dist::Base - Base class for custom distribution classes +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Dist::Base, +CPANPLUS::Dist::Base - Base class for custom distribution classes =over 4 @@ -17749,7 +18534,8 @@ $version_spec ) =back -=head2 CPANPLUS::Dist::Build - CPANPLUS plugin to install packages that use +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Dist::Build, +CPANPLUS::Dist::Build - CPANPLUS plugin to install packages that use Build.PL =over 4 @@ -17816,8 +18602,8 @@ prereq_target => TARGET, force => BOOL, verbose => BOOL, skiptest => BOOL]) =back -=head2 CPANPLUS::Dist::Build::Constants - Constants for -CPANPLUS::Dist::Build +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Dist::Build::Constants, +CPANPLUS::Dist::Build::Constants - Constants for CPANPLUS::Dist::Build =over 4 @@ -17831,12 +18617,14 @@ CPANPLUS::Dist::Build =back -=head2 CPANPLUS::Dist::MM +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Dist::MM, CPANPLUS::Dist::MM =over 4 =item SYNOPSIS +=item DESCRIPTION + =item ACCESSORS parent(), status() @@ -17862,6 +18650,19 @@ installed (), uninstalled (), _create_args (), _install_args () =over 4 +=item $bool = $dist->init(); + +=back + +=over 4 + +=item $bool = $dist->prepare([perl => '/path/to/perl', makemakerflags => +'EXTRA=FLAGS', force => BOOL, verbose => BOOL]) + +=back + +=over 4 + =item $href = $dist->_find_prereqs( file => '/path/to/Makefile', [verbose => BOOL]) @@ -17888,8 +18689,8 @@ skiptest => BOOL, force => BOOL, verbose => BOOL]) =back -=head2 CPANPLUS::Dist::Sample -- Sample code to create your own Dist::* -plugin +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Dist::Sample, +CPANPLUS::Dist::Sample -- Sample code to create your own Dist::* plugin =over 4 @@ -17897,7 +18698,7 @@ plugin =back -=head2 CPANPLUS::Error +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Error, CPANPLUS::Error =over 4 @@ -17941,7 +18742,7 @@ $ERROR_FH, $MSG_FH =back -=head2 CPANPLUS::FAQ +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::FAQ, CPANPLUS::FAQ =over 4 @@ -17955,7 +18756,7 @@ $ERROR_FH, $MSG_FH =back -=head2 CPANPLUS::Hacking +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Hacking, CPANPLUS::Hacking =over 4 @@ -17986,7 +18787,7 @@ description of the patch =back -=head2 CPANPLUS::Internals +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals, CPANPLUS::Internals =over 4 @@ -18048,7 +18849,8 @@ edit_test_report, proceed_on_test_failure, munge_dist_metafile =back -=head2 CPANPLUS::Internals::Extract +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals::Extract, +CPANPLUS::Internals::Extract =over 4 @@ -18056,6 +18858,8 @@ edit_test_report, proceed_on_test_failure, munge_dist_metafile =item DESCRIPTION +=item METHODS + =over 4 =item $dir = _extract( module => $modobj, [perl => '/path/to/perl', @@ -18068,7 +18872,8 @@ module, extractdir, prefer_bin, perl, verbose, force =back -=head2 CPANPLUS::Internals::Fetch +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals::Fetch, +CPANPLUS::Internals::Fetch =over 4 @@ -18096,7 +18901,8 @@ BOOL, prefer_bin => BOOL, ttl => $seconds] ) =back -=head2 CPANPLUS::Internals::Report +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals::Report, +CPANPLUS::Internals::Report =over 4 @@ -18133,7 +18939,8 @@ module, buffer, failed, save, address, verbose, force =back -=head2 CPANPLUS::Internals::Search +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals::Search, +CPANPLUS::Internals::Search =over 4 @@ -18169,7 +18976,8 @@ type, allow, data =back -=head2 CPANPLUS::Internals::Source +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals::Source, +CPANPLUS::Internals::Source =over 4 @@ -18301,7 +19109,8 @@ BOOL] ); =back -=head2 CPANPLUS::Internals::Source::Memory - In memory implementation +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals::Source::Memory, +CPANPLUS::Internals::Source::Memory - In memory implementation =over 4 @@ -18320,9 +19129,11 @@ path, verbose =back -=head2 CPANPLUS::Internals::Source::SQLite - SQLite implementation +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals::Source::SQLite, +CPANPLUS::Internals::Source::SQLite - SQLite implementation -=head2 CPANPLUS::Internals::Utils +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Internals::Utils, +CPANPLUS::Internals::Utils =over 4 @@ -18378,6 +19189,18 @@ path, verbose =over 4 +=item $cb->_move( from => $file|$dir, to => $target ); + +=back + +=over 4 + +=item $cb->_copy( from => $file|$dir, to => $target ); + +=back + +=over 4 + =item $cb->_mode_plus_w( file => '/path/to/file' ); =back @@ -18414,7 +19237,7 @@ PACKAGE_STRING ); =back -=head2 CPANPLUS::Module +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Module, CPANPLUS::Module =over 4 @@ -18521,10 +19344,6 @@ DISTRIBUTION_TYPE, args => {key => val}]); =item $bool = $mod->prepare( ) -Convenience method around C<install()> that prepares a module -without actually building it. This is equivalent to invoking C<install> -with C<target> set to C<prepare> - =back =over 4 @@ -18625,7 +19444,8 @@ prefer_bin => BOOL, force => BOOL, verbose => BOOL, ..... ]); =back -=head2 CPANPLUS::Module::Author +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Module::Author, +CPANPLUS::Module::Author =over 4 @@ -18676,7 +19496,8 @@ author, cpanid, email, parent =back -=head2 CPANPLUS::Module::Author::Fake +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Module::Author::Fake, +CPANPLUS::Module::Author::Fake =over 4 @@ -18694,7 +19515,8 @@ author, cpanid, email, parent =back -=head2 CPANPLUS::Module::Checksums +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Module::Checksums, +CPANPLUS::Module::Checksums =over 4 @@ -18712,7 +19534,8 @@ author, cpanid, email, parent =back -=head2 CPANPLUS::Module::Fake +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Module::Fake, +CPANPLUS::Module::Fake =over 4 @@ -18730,7 +19553,8 @@ author, cpanid, email, parent =back -=head2 CPANPLUSelfupdate, CPANPLUS::Selfupdate +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Selfupdate, +CPANPLUS::Selfupdate =over 4 @@ -18755,9 +19579,13 @@ author, cpanid, email, parent =item %list = $self->list_modules_to_update( update => "core|dependencies|enabled_features|features|all", [latest => BOOL] ) -List which modules C<selfupdate> would upgrade. You can update either -the core (CPANPLUS itself), the core dependencies, all features you have -currently turned on, or all features available, or everything. +=back + +=over 4 + +=item $bool = $self->selfupdate( update => +"core|dependencies|enabled_features|features|all", [latest => BOOL, force +=> BOOL] ) =back @@ -18819,7 +19647,7 @@ currently turned on, or all features available, or everything. =back -=head2 CPANPLUShell, CPANPLUS::Shell +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Shell, CPANPLUS::Shell =over 4 @@ -18841,8 +19669,8 @@ currently turned on, or all features available, or everything. =back -=head2 CPANPLUShell::Classic, CPANPLUS::Shell::Classic - CPAN.pm emulation -for CPANPLUS +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Shell::Classic, +CPANPLUS::Shell::Classic - CPAN.pm emulation for CPANPLUS =over 4 @@ -18864,7 +19692,8 @@ for CPANPLUS =back -=head2 CPANPLUShell::Default, CPANPLUS::Shell::Default +=head2 C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Shell::Default, +CPANPLUS::Shell::Default =over 4 @@ -18886,21 +19715,20 @@ for CPANPLUS =back -=head2 CPANPLUShell::Default::Plugins::CustomSource, -CPANPLUS::Shell::Default::Plugins::CustomSource +=head2 +C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Shell::Default::Plugins::CustomSource +, CPANPLUS::Shell::Default::Plugins::CustomSource =over 4 =item SYNOPSIS - ### elaborate help text - CPAN Terminal> /? cs - =item DESCRIPTION =back -=head2 CPANPLUShell::Default::Plugins::HOWTO, +=head2 +C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Shell::Default::Plugins::HOWTO, CPANPLUS::Shell::Default::Plugins::HOWTO -- documentation on how to write your own plugins @@ -18937,7 +19765,8 @@ from the user, Options -- A hashref of options provided by the user =back -=head2 CPANPLUShell::Default::Plugins::Remote, +=head2 +C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Shell::Default::Plugins::Remote, CPANPLUS::Shell::Default::Plugins::Remote =over 4 @@ -18960,7 +19789,8 @@ CPANPLUS::Shell::Default::Plugins::Remote =back -=head2 CPANPLUShell::Default::Plugins::Source, +=head2 +C:\perl_tl\perl-5.14.2\lib::CPANPLUS::Shell::Default::Plugins::Source, CPANPLUS::Shell::Default::Plugins::Source =over 4 @@ -18983,22 +19813,8 @@ CPANPLUS::Shell::Default::Plugins::Source =back -=head2 CPANox, CPAN::Nox - Wrapper around CPAN.pm without using any XS -module - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item LICENSE - -=item SEE ALSO - -=back - -=head2 Carp, carp - warn of errors (from perspective of caller) +=head2 C:\perl_tl\perl-5.14.2\lib::Carp, Carp - alternative warn and die +for modules =over 4 @@ -19038,31 +19854,8 @@ module =back -=head2 Class::ISA - report the search path for a class's ISA tree - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item FUNCTIONS - -the function Class::ISA::super_path($CLASS), the function -Class::ISA::self_and_super_path($CLASS), the function -Class::ISA::self_and_super_versions($CLASS) - -=item CAUTIONARY NOTES - -=item COPYRIGHT AND LICENSE - -=item AUTHOR - -=item MAINTAINER - -=back - -=head2 Class::Struct - declare struct-like datatypes as Perl classes +=head2 C:\perl_tl\perl-5.14.2\lib::Class::Struct, Class::Struct - declare +struct-like datatypes as Perl classes =over 4 @@ -19093,8 +19886,8 @@ Example 1, Example 2, Example 3 =back -=head2 Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression -library +=head2 C:\perl_tl\perl-5.14.2\lib::Compress::Raw::Bzip2, +Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library =over 4 @@ -19126,9 +19919,10 @@ B<$appendOutput>, B<$blockSize100k>, B<$workfactor> =over 4 =item ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, -$consumeInput, $small, $limitOutput; +$consumeInput, $small, $verbosity, $limitOutput; -B<$appendOutput>, B<$consumeInput>, B<$small>, B<$limitOutput> +B<$appendOutput>, B<$consumeInput>, B<$small>, B<$limitOutput>, +B<$verbosity> =item $status = $z->bzinflate($input, $output); @@ -19154,8 +19948,8 @@ B<$appendOutput>, B<$consumeInput>, B<$small>, B<$limitOutput> =back -=head2 Compress::Raw::Zlib - Low-Level Interface to zlib compression -library +=head2 C:\perl_tl\perl-5.14.2\lib::Compress::Raw::Zlib, Compress::Raw::Zlib +- Low-Level Interface to zlib compression library =over 4 @@ -19220,6 +20014,8 @@ B<-ADLER32>, B<-ConsumeInput>, B<-LimitOutput> =item B<$status = $i-E<gt>inflateSync($input)> +=item B<$status = $i-E<gt>inflateReset() > + =item B<$i-E<gt>dict_adler()> =item B<$i-E<gt>crc32()> @@ -19264,7 +20060,8 @@ B<-ADLER32>, B<-ConsumeInput>, B<-LimitOutput> =back -=head2 Compress::Zlib - Interface to zlib compression library +=head2 C:\perl_tl\perl-5.14.2\lib::Compress::Zlib, Compress::Zlib - +Interface to zlib compression library =over 4 @@ -19379,7 +20176,8 @@ B<-WindowBits>, B<-Bufsize>, B<-Dictionary> =back -=head2 Config - access Perl configuration information +=head2 C:\perl_tl\perl-5.14.2\lib::Config, Config - access Perl +configuration information =over 4 @@ -19387,7 +20185,9 @@ B<-WindowBits>, B<-Bufsize>, B<-Dictionary> =item DESCRIPTION -myconfig(), config_sh(), config_re($regex), config_vars(@names) +myconfig(), config_sh(), config_re($regex), config_vars(@names), +bincompat_options(), non_bincompat_options(), compile_date(), +local_patches(), header_files() =item EXAMPLE @@ -19505,34 +20305,35 @@ 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>, -C<d_phostname>, C<d_pipe>, C<d_poll>, C<d_portable>, C<d_PRId64>, -C<d_PRIeldbl>, C<d_PRIEUldbl>, C<d_PRIfldbl>, C<d_PRIFUldbl>, -C<d_PRIgldbl>, C<d_PRIGUldbl>, C<d_PRIi64>, C<d_printf_format_null>, -C<d_PRIo64>, C<d_PRIu64>, C<d_PRIx64>, C<d_PRIXU64>, C<d_procselfexe>, -C<d_pseudofork>, C<d_pthread_atfork>, C<d_pthread_attr_setscope>, -C<d_pthread_yield>, C<d_pwage>, C<d_pwchange>, C<d_pwclass>, -C<d_pwcomment>, C<d_pwexpire>, C<d_pwgecos>, C<d_pwpasswd>, C<d_pwquota>, -C<d_qgcvt>, C<d_quad>, C<d_random_r>, C<d_readdir>, C<d_readdir64_r>, -C<d_readdir_r>, C<d_readlink>, C<d_readv>, C<d_recvmsg>, C<d_rename>, -C<d_rewinddir>, C<d_rmdir>, C<d_safebcpy>, C<d_safemcpy>, C<d_sanemcmp>, -C<d_sbrkproto>, C<d_scalbnl>, C<d_sched_yield>, C<d_scm_rights>, -C<d_SCNfldbl>, C<d_seekdir>, C<d_select>, C<d_sem>, C<d_semctl>, -C<d_semctl_semid_ds>, C<d_semctl_semun>, C<d_semget>, C<d_semop>, -C<d_sendmsg>, C<d_setegid>, C<d_seteuid>, C<d_setgrent>, C<d_setgrent_r>, -C<d_setgrps>, C<d_sethent>, C<d_sethostent_r>, C<d_setitimer>, -C<d_setlinebuf>, C<d_setlocale>, C<d_setlocale_r>, C<d_setnent>, -C<d_setnetent_r>, C<d_setpent>, C<d_setpgid>, C<d_setpgrp>, C<d_setpgrp2>, -C<d_setprior>, C<d_setproctitle>, C<d_setprotoent_r>, C<d_setpwent>, -C<d_setpwent_r>, C<d_setregid>, C<d_setresgid>, C<d_setresuid>, -C<d_setreuid>, C<d_setrgid>, C<d_setruid>, C<d_setsent>, C<d_setservent_r>, -C<d_setsid>, C<d_setvbuf>, C<d_sfio>, C<d_shm>, C<d_shmat>, -C<d_shmatprototype>, C<d_shmctl>, C<d_shmdt>, C<d_shmget>, C<d_sigaction>, -C<d_signbit>, C<d_sigprocmask>, C<d_sigsetjmp>, C<d_sitearch>, -C<d_snprintf>, C<d_sockatmark>, C<d_sockatmarkproto>, C<d_socket>, -C<d_socklen_t>, C<d_sockpair>, C<d_socks5_init>, -C<d_sprintf_returns_strlen>, C<d_sqrtl>, C<d_srand48_r>, C<d_srandom_r>, -C<d_sresgproto>, C<d_sresuproto>, C<d_statblks>, C<d_statfs_f_flags>, -C<d_statfs_s>, C<d_statvfs>, C<d_stdio_cnt_lval>, C<d_stdio_ptr_lval>, +C<d_phostname>, C<d_pipe>, C<d_poll>, C<d_portable>, C<d_prctl>, +C<d_prctl_set_name>, C<d_PRId64>, C<d_PRIeldbl>, C<d_PRIEUldbl>, +C<d_PRIfldbl>, C<d_PRIFUldbl>, C<d_PRIgldbl>, C<d_PRIGUldbl>, C<d_PRIi64>, +C<d_printf_format_null>, C<d_PRIo64>, C<d_PRIu64>, C<d_PRIx64>, +C<d_PRIXU64>, C<d_procselfexe>, C<d_pseudofork>, C<d_pthread_atfork>, +C<d_pthread_attr_setscope>, C<d_pthread_yield>, C<d_pwage>, C<d_pwchange>, +C<d_pwclass>, C<d_pwcomment>, C<d_pwexpire>, C<d_pwgecos>, C<d_pwpasswd>, +C<d_pwquota>, C<d_qgcvt>, C<d_quad>, C<d_random_r>, C<d_readdir>, +C<d_readdir64_r>, C<d_readdir_r>, C<d_readlink>, C<d_readv>, C<d_recvmsg>, +C<d_rename>, C<d_rewinddir>, C<d_rmdir>, C<d_safebcpy>, C<d_safemcpy>, +C<d_sanemcmp>, C<d_sbrkproto>, C<d_scalbnl>, C<d_sched_yield>, +C<d_scm_rights>, C<d_SCNfldbl>, C<d_seekdir>, C<d_select>, C<d_sem>, +C<d_semctl>, C<d_semctl_semid_ds>, C<d_semctl_semun>, C<d_semget>, +C<d_semop>, C<d_sendmsg>, C<d_setegid>, C<d_seteuid>, C<d_setgrent>, +C<d_setgrent_r>, C<d_setgrps>, C<d_sethent>, C<d_sethostent_r>, +C<d_setitimer>, C<d_setlinebuf>, C<d_setlocale>, C<d_setlocale_r>, +C<d_setnent>, C<d_setnetent_r>, C<d_setpent>, C<d_setpgid>, C<d_setpgrp>, +C<d_setpgrp2>, C<d_setprior>, C<d_setproctitle>, C<d_setprotoent_r>, +C<d_setpwent>, C<d_setpwent_r>, C<d_setregid>, C<d_setresgid>, +C<d_setresuid>, C<d_setreuid>, C<d_setrgid>, C<d_setruid>, C<d_setsent>, +C<d_setservent_r>, C<d_setsid>, C<d_setvbuf>, C<d_sfio>, C<d_shm>, +C<d_shmat>, C<d_shmatprototype>, C<d_shmctl>, C<d_shmdt>, C<d_shmget>, +C<d_sigaction>, C<d_signbit>, C<d_sigprocmask>, C<d_sigsetjmp>, +C<d_sin6_scope_id>, C<d_sitearch>, C<d_snprintf>, C<d_sockaddr_sa_len>, +C<d_sockatmark>, C<d_sockatmarkproto>, C<d_socket>, C<d_socklen_t>, +C<d_sockpair>, C<d_socks5_init>, C<d_sprintf_returns_strlen>, C<d_sqrtl>, +C<d_srand48_r>, C<d_srandom_r>, C<d_sresgproto>, C<d_sresuproto>, +C<d_statblks>, C<d_statfs_f_flags>, C<d_statfs_s>, C<d_static_inline>, +C<d_statvfs>, C<d_stdio_cnt_lval>, C<d_stdio_ptr_lval>, C<d_stdio_ptr_lval_nochange_cnt>, C<d_stdio_ptr_lval_sets_cnt>, C<d_stdio_stream_array>, C<d_stdiobase>, C<d_stdstdio>, C<d_strchr>, C<d_strcoll>, C<d_strctcpy>, C<d_strerrm>, C<d_strerror>, C<d_strerror_r>, @@ -19709,10 +20510,11 @@ C<perl5> C<PERL_API_REVISION>, C<PERL_API_SUBVERSION>, C<PERL_API_VERSION>, C<PERL_CONFIG_SH>, C<PERL_PATCHLEVEL>, C<perl_patchlevel>, -C<PERL_REVISION>, C<PERL_SUBVERSION>, C<PERL_VERSION>, C<perladmin>, -C<perllibs>, C<perlpath>, C<pg>, C<phostname>, C<pidtype>, C<plibpth>, -C<pmake>, C<pr>, C<prefix>, C<prefixexp>, C<privlib>, C<privlibexp>, -C<procselfexe>, C<prototype>, C<ptrsize> +C<PERL_REVISION>, C<perl_static_inline>, C<PERL_SUBVERSION>, +C<PERL_VERSION>, C<perladmin>, C<perllibs>, C<perlpath>, C<pg>, +C<phostname>, C<pidtype>, C<plibpth>, C<pmake>, C<pr>, C<prefix>, +C<prefixexp>, C<privlib>, C<privlibexp>, C<procselfexe>, C<prototype>, +C<ptrsize> =over 4 @@ -19846,7 +20648,8 @@ dynamic, nonxs, static =back -=head2 Cwd - get pathname of current working directory +=head2 C:\perl_tl\perl-5.14.2\lib::Cwd, Cwd - get pathname of current +working directory =over 4 @@ -19878,7 +20681,8 @@ abs_path, realpath, fast_abs_path =back -=head2 DB - programmatic interface to the Perl debugging API +=head2 C:\perl_tl\perl-5.14.2\lib::DB, DB - programmatic interface to the +Perl debugging API =over 4 @@ -19913,7 +20717,8 @@ CLIENT->output(LIST) =back -=head2 DBM_Filter -- Filter DBM keys/values +=head2 C:\perl_tl\perl-5.14.2\lib::DBM_Filter, DBM_Filter -- Filter DBM +keys/values =over 4 @@ -19933,11 +20738,8 @@ CLIENT->output(LIST) =over 4 -=item $db->Filter_Push() - -=item $db->Filter_Key_Push() - -=item $db->Filter_Value_Push() +=item $db->Filter_Push() / $db->Filter_Key_Push() / +$db->Filter_Value_Push() Filter_Push, Filter_Key_Push, Filter_Value_Push @@ -19981,7 +20783,8 @@ utf8, encode, compress, int32, null =back -=head2 DBM_Filter::compress - filter for DBM_Filter +=head2 C:\perl_tl\perl-5.14.2\lib::DBM_Filter::compress, +DBM_Filter::compress - filter for DBM_Filter =over 4 @@ -19995,7 +20798,8 @@ utf8, encode, compress, int32, null =back -=head2 DBM_Filter::encode - filter for DBM_Filter +=head2 C:\perl_tl\perl-5.14.2\lib::DBM_Filter::encode, DBM_Filter::encode - +filter for DBM_Filter =over 4 @@ -20009,7 +20813,8 @@ utf8, encode, compress, int32, null =back -=head2 DBM_Filter::int32 - filter for DBM_Filter +=head2 C:\perl_tl\perl-5.14.2\lib::DBM_Filter::int32, DBM_Filter::int32 - +filter for DBM_Filter =over 4 @@ -20023,7 +20828,8 @@ utf8, encode, compress, int32, null =back -=head2 DBM_Filter::null - filter for DBM_Filter +=head2 C:\perl_tl\perl-5.14.2\lib::DBM_Filter::null, DBM_Filter::null - +filter for DBM_Filter =over 4 @@ -20037,7 +20843,8 @@ utf8, encode, compress, int32, null =back -=head2 DBM_Filter::utf8 - filter for DBM_Filter +=head2 C:\perl_tl\perl-5.14.2\lib::DBM_Filter::utf8, DBM_Filter::utf8 - +filter for DBM_Filter =over 4 @@ -20051,8 +20858,8 @@ utf8, encode, compress, int32, null =back -=head2 Data::Dumper - stringified perl data structures, suitable for both -printing and C<eval> +=head2 C:\perl_tl\perl-5.14.2\lib::Data::Dumper, Data::Dumper - stringified +perl data structures, suitable for both printing and C<eval> =over 4 @@ -20099,93 +20906,14 @@ Dumper =back -=head2 Devel-DProf, Devel::DProf - a Perl code profiler - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item PROFILE FORMAT - -=item AUTOLOAD - -=item ENVIRONMENT - -=item BUGS - -=item SEE ALSO - -=back - -=head2 Devel-Peek, Devel::Peek - A data debugging tool for the XS -programmer - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Runtime debugging - -=item Memory footprint debugging - -=back - -=item EXAMPLES - -=over 4 - -=item A simple scalar string - -=item A simple scalar number - -=item A simple scalar with an extra reference - -=item A reference to a simple scalar - -=item A reference to an array - -=item A reference to a hash - -=item Dumping a large array or hash - -=item A reference to an SV which holds a C pointer - -=item A reference to a subroutine - -=back - -=item EXPORTS - -=item BUGS - -=item AUTHOR - -=item SEE ALSO - -=back - -=head2 Devel-SelfStubber::lib::Devel::SelfStubber, Devel::SelfStubber - -generate stubs for a SelfLoading module +=head2 C:\perl_tl\perl-5.14.2\lib::Devel::DProf, Devel::DProf - a +B<DEPRECATED> Perl code profiler =over 4 =item SYNOPSIS -=item DESCRIPTION - -=back - -=head2 Devel::DProf - a Perl code profiler - -=over 4 - -=item SYNOPSIS +=item ACHTUNG! =item DESCRIPTION @@ -20201,7 +20929,8 @@ generate stubs for a SelfLoading module =back -=head2 Devel::InnerPackage - find all the inner packages of a package +=head2 C:\perl_tl\perl-5.14.2\lib::Devel::InnerPackage, Devel::InnerPackage +- find all the inner packages of a package =over 4 @@ -20229,7 +20958,8 @@ generate stubs for a SelfLoading module =back -=head2 Devel::PPPort - Perl/Pollution/Portability +=head2 C:\perl_tl\perl-5.14.2\lib::Devel::PPPort, Devel::PPPort - +Perl/Pollution/Portability =over 4 @@ -20280,7 +21010,8 @@ perl 5.004_05, perl 5.004 =back -=head2 Devel::Peek - A data debugging tool for the XS programmer +=head2 C:\perl_tl\perl-5.14.2\lib::Devel::Peek, Devel::Peek - A data +debugging tool for the XS programmer =over 4 @@ -20330,7 +21061,8 @@ perl 5.004_05, perl 5.004 =back -=head2 Devel::SelfStubber - generate stubs for a SelfLoading module +=head2 C:\perl_tl\perl-5.14.2\lib::Devel::SelfStubber, Devel::SelfStubber - +generate stubs for a SelfLoading module =over 4 @@ -20340,7 +21072,8 @@ perl 5.004_05, perl 5.004 =back -=head2 Digest - Modules that calculate message digests +=head2 C:\perl_tl\perl-5.14.2\lib::Digest, Digest - Modules that calculate +message digests =over 4 @@ -20366,7 +21099,8 @@ $io_handle ), $ctx->add_bits( $data, $nbits ), $ctx->add_bits( $bitstring =back -=head2 Digest::MD5 - Perl interface to the MD5 Algorithm +=head2 C:\perl_tl\perl-5.14.2\lib::Digest::MD5, Digest::MD5 - Perl +interface to the MD5 Algorithm =over 4 @@ -20394,7 +21128,8 @@ $md5->add_bits($bitstring), $md5->digest, $md5->hexdigest, $md5->b64digest =back -=head2 Digest::SHA - Perl extension for SHA-1/224/256/384/512 +=head2 C:\perl_tl\perl-5.14.2\lib::Digest::SHA, Digest::SHA - Perl +extension for SHA-1/224/256/384/512 =over 4 @@ -20415,22 +21150,29 @@ $md5->add_bits($bitstring), $md5->digest, $md5->hexdigest, $md5->b64digest =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<sha384($data, ...)>, B<sha512($data, ...)>, B<sha512224($data, ...)>, +B<sha512256($data, ...)>, B<sha1_hex($data, ...)>, B<sha224_hex($data, +...)>, B<sha256_hex($data, ...)>, B<sha384_hex($data, ...)>, +B<sha512_hex($data, ...)>, B<sha512224_hex($data, ...)>, +B<sha512256_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)> +B<sha384_base64($data, ...)>, B<sha512_base64($data, ...)>, +B<sha512224_base64($data, ...)>, B<sha512256_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_sha512224($data, $key)>, +B<hmac_sha512256($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_sha512224_hex($data, $key)>, B<hmac_sha512256_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)>, B<hmac_sha512224_base64($data, $key)>, +B<hmac_sha512256_base64($data, $key)> =item SEE ALSO @@ -20442,7 +21184,8 @@ B<hmac_sha384_base64($data, $key)>, B<hmac_sha512_base64($data, $key)> =back -=head2 Digest::base - Digest base class +=head2 C:\perl_tl\perl-5.14.2\lib::Digest::base, Digest::base - Digest base +class =over 4 @@ -20454,7 +21197,8 @@ B<hmac_sha384_base64($data, $key)>, B<hmac_sha512_base64($data, $key)> =back -=head2 Digest::file - Calculate digests of files +=head2 C:\perl_tl\perl-5.14.2\lib::Digest::file, Digest::file - Calculate +digests of files =over 4 @@ -20470,7 +21214,8 @@ $algorithm, [$arg,...] ), digest_file_base64( $file, $algorithm, [$arg,...] =back -=head2 DirHandle - supply object methods for directory handles +=head2 C:\perl_tl\perl-5.14.2\lib::DirHandle, DirHandle - supply object +methods for directory handles =over 4 @@ -20478,11 +21223,10 @@ $algorithm, [$arg,...] ), digest_file_base64( $file, $algorithm, [$arg,...] =item DESCRIPTION -=item NOTES - =back -=head2 Dumpvalue - provides screen dump of Perl data. +=head2 C:\perl_tl\perl-5.14.2\lib::Dumpvalue, Dumpvalue - provides screen +dump of Perl data. =over 4 @@ -20508,7 +21252,8 @@ compactDump, veryCompact, set, get =back -=head2 DynaLoader - Dynamically load C libraries into Perl code +=head2 C:\perl_tl\perl-5.14.2\lib::DynaLoader, DynaLoader - Dynamically +load C libraries into Perl code =over 4 @@ -20526,7 +21271,7 @@ dl_install_xsub(), bootstrap() =back -=head2 Encode - character encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode, Encode - character encodings =over 4 @@ -20604,7 +21349,8 @@ is_utf8(STRING [, CHECK]), _utf8_on(STRING), _utf8_off(STRING) =back -=head2 Encode::Alias - alias definitions to encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Alias, Encode::Alias - alias +definitions to encodings =over 4 @@ -20625,7 +21371,8 @@ reference, e.g.: =back -=head2 Encode::Byte - Single Byte Encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Byte, Encode::Byte - Single Byte +Encodings =over 4 @@ -20639,9 +21386,11 @@ reference, e.g.: =back -=head2 Encode::CJKConstants -- Internally used by Encode::??::ISO_2022_* +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::CJKConstants, +Encode::CJKConstants.pm -- Internally used by Encode::??::ISO_2022_* -=head2 Encode::CN - China-based Chinese Encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::CN, Encode::CN - China-based +Chinese Encodings =over 4 @@ -20657,11 +21406,14 @@ reference, e.g.: =back -=head2 Encode::CN::HZ -- internally used by Encode::CN +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::CN::HZ, Encode::CN::HZ -- +internally used by Encode::CN -=head2 Encode::Config -- internally used by Encode +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Config, Encode::Config -- +internally used by Encode -=head2 Encode::EBCDIC - EBCDIC Encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::EBCDIC, Encode::EBCDIC - EBCDIC +Encodings =over 4 @@ -20675,7 +21427,37 @@ reference, e.g.: =back -=head2 Encode::Encoding - Encode Implementation Base Class +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Encoder, Encode::Encoder -- +Object Oriented Encoder + +=over 4 + +=item SYNOPSIS + +=item ABSTRACT + +=item Description + +=over 4 + +=item Predefined Methods + +$e = Encode::Encoder-E<gt>new([$data, $encoding]);, encoder(), +$e-E<gt>data([$data]), $e-E<gt>encoding([$encoding]), +$e-E<gt>bytes([$encoding]) + +=item Example: base64 transcoder + +=item Operator Overloading + +=back + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Encoding, Encode::Encoding - +Encode Implementation Base Class =over 4 @@ -20713,7 +21495,8 @@ Scheme 1, Scheme 2, Other Schemes =back -=head2 Encode::GSM0338 -- ESTI GSM 03.38 Encoding +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::GSM0338, Encode::GSM0338 -- ESTI +GSM 03.38 Encoding =over 4 @@ -20729,7 +21512,8 @@ Scheme 1, Scheme 2, Other Schemes =back -=head2 Encode::Guess -- Guesses encoding from data +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Guess, Encode::Guess -- Guesses +encoding from data =over 4 @@ -20751,7 +21535,8 @@ guess_encoding($data, [, I<list of suspects>]) =back -=head2 Encode::JP - Japanese Encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::JP, Encode::JP - Japanese +Encodings =over 4 @@ -20769,11 +21554,14 @@ guess_encoding($data, [, I<list of suspects>]) =back -=head2 Encode::JP::H2Z -- internally used by Encode::JP::2022_JP* +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::JP::H2Z, Encode::JP::H2Z -- +internally used by Encode::JP::2022_JP* -=head2 Encode::JP::JIS7 -- internally used by Encode::JP +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::JP::JIS7, Encode::JP::JIS7 -- +internally used by Encode::JP -=head2 Encode::KR - Korean Encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::KR, Encode::KR - Korean +Encodings =over 4 @@ -20787,9 +21575,11 @@ guess_encoding($data, [, I<list of suspects>]) =back -=head2 Encode::KR::2022_KR -- internally used by Encode::KR +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::KR::2022_KR, Encode::KR::2022_KR +-- internally used by Encode::KR -=head2 Encode::MIME::Header -- MIME 'B' and 'Q' header encoding +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::MIME::Header, +Encode::MIME::Header -- MIME 'B' and 'Q' header encoding =over 4 @@ -20805,7 +21595,8 @@ guess_encoding($data, [, I<list of suspects>]) =back -=head2 Encode::MIME::Name, Encode::MIME::NAME -- internally used by Encode +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::MIME::Name, Encode::MIME::NAME +-- internally used by Encode =over 4 @@ -20813,7 +21604,8 @@ guess_encoding($data, [, I<list of suspects>]) =back -=head2 Encode::PerlIO -- a detailed document on Encode and PerlIO +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::PerlIO, Encode::PerlIO -- a +detailed document on Encode and PerlIO =over 4 @@ -20833,7 +21625,8 @@ guess_encoding($data, [, I<list of suspects>]) =back -=head2 Encode::Supported -- Encodings supported by Encode +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Supported, Encode::Supported -- +Encodings supported by Encode =over 4 @@ -20921,7 +21714,8 @@ C<CJKV Information Processing> by Ken Lunde =back -=head2 Encode::Symbol - Symbol Encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Symbol, Encode::Symbol - Symbol +Encodings =over 4 @@ -20935,7 +21729,8 @@ C<CJKV Information Processing> by Ken Lunde =back -=head2 Encode::TW - Taiwan-based Chinese Encodings +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::TW, Encode::TW - Taiwan-based +Chinese Encodings =over 4 @@ -20951,7 +21746,8 @@ C<CJKV Information Processing> by Ken Lunde =back -=head2 Encode::Unicode -- Various Unicode Transformation Formats +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Unicode, Encode::Unicode -- +Various Unicode Transformation Formats =over 4 @@ -20981,7 +21777,8 @@ BOM as integer when fetched in network byte order =back -=head2 Encode::Unicode::UTF7 -- UTF-7 encoding +=head2 C:\perl_tl\perl-5.14.2\lib::Encode::Unicode::UTF7, +Encode::Unicode::UTF7 -- UTF-7 encoding =over 4 @@ -20995,36 +21792,8 @@ BOM as integer when fetched in network byte order =back -=head2 Encoder, Encode::Encoder -- Object Oriented Encoder - -=over 4 - -=item SYNOPSIS - -=item ABSTRACT - -=item Description - -=over 4 - -=item Predefined Methods - -$e = Encode::Encoder-E<gt>new([$data, $encoding]);, encoder(), -$e-E<gt>data([$data]), $e-E<gt>encoding([$encoding]), -$e-E<gt>bytes([$encoding]) - -=item Example: base64 transcoder - -=item Operator Overloading - -=back - -=item SEE ALSO - -=back - -=head2 English - use nice English (or awk) names for ugly punctuation -variables +=head2 C:\perl_tl\perl-5.14.2\lib::English, English - use nice English (or +awk) names for ugly punctuation variables =over 4 @@ -21036,8 +21805,8 @@ variables =back -=head2 Env - perl module that imports environment variables as scalars or -arrays +=head2 C:\perl_tl\perl-5.14.2\lib::Env, Env - perl module that imports +environment variables as scalars or arrays =over 4 @@ -21051,7 +21820,7 @@ arrays =back -=head2 Errno - System errno constants +=head2 C:\perl_tl\perl-5.14.2\lib::Errno, Errno - System errno constants =over 4 @@ -21067,7 +21836,8 @@ arrays =back -=head2 Exporter - Implements default import method for modules +=head2 C:\perl_tl\perl-5.14.2\lib::Exporter, Exporter - Implements default +import method for modules =over 4 @@ -21127,7 +21897,8 @@ C<use YourModule;>, C<use YourModule ();>, C<use YourModule qw(...);> =back -=head2 Exporter::Heavy - Exporter guts +=head2 C:\perl_tl\perl-5.14.2\lib::Exporter::Heavy, Exporter::Heavy - +Exporter guts =over 4 @@ -21137,7 +21908,8 @@ C<use YourModule;>, C<use YourModule ();>, C<use YourModule qw(...);> =back -=head2 ExtUtils::CBuilder - Compile and link C code for Perl modules +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::CBuilder, ExtUtils::CBuilder - +Compile and link C code for Perl modules =over 4 @@ -21164,8 +21936,8 @@ lib_file, exe_file, prelink, need_prelink, extra_link_args_after_prelink =back -=head2 ExtUtils::CBuilder::Platform::Windows - Builder class for Windows -platforms +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::CBuilder::Platform::Windows, +ExtUtils::CBuilder::Platform::Windows - Builder class for Windows platforms =over 4 @@ -21177,8 +21949,8 @@ platforms =back -=head2 ExtUtils::Command - utilities to replace common UNIX commands in -Makefiles etc. +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Command, ExtUtils::Command - +utilities to replace common UNIX commands in Makefiles etc. =over 4 @@ -21226,7 +21998,8 @@ dos2unix =back -=head2 ExtUtils::Command::MM - Commands for the MM's to use in Makefiles +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Command::MM, +ExtUtils::Command::MM - Commands for the MM's to use in Makefiles =over 4 @@ -21246,7 +22019,8 @@ B<perllocal_install> B<uninstall> -=head2 ExtUtils::Constant - generate XS code to import C header constants +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Constant, ExtUtils::Constant - +generate XS code to import C header constants =over 4 @@ -21280,7 +22054,8 @@ C_SUBNAME =back -=head2 ExtUtils::Constant::Base - base class for ExtUtils::Constant objects +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Constant::Base, +ExtUtils::Constant::Base - base class for ExtUtils::Constant objects =over 4 @@ -21321,7 +22096,8 @@ post, def_pre, def_post, utf8, weight =back -=head2 ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Constant::Utils, +ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant =over 4 @@ -21343,7 +22119,8 @@ perl_stringify NAME =back -=head2 ExtUtils::Constant::XS - generate C code for XS modules' constants. +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Constant::XS, +ExtUtils::Constant::XS - generate C code for XS modules' constants. =over 4 @@ -21357,7 +22134,8 @@ perl_stringify NAME =back -=head2 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Embed, ExtUtils::Embed - +Utilities for embedding Perl in C/C++ applications =over 4 @@ -21380,7 +22158,8 @@ ccopts(), xsi_header(), xsi_protos(@modules), xsi_body(@modules) =back -=head2 ExtUtils::Install - install files from here to there +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Install, ExtUtils::Install - +install files from here to there =over 4 @@ -21457,7 +22236,8 @@ B<EU_INSTALL_SITE_SKIPFILE>, B<EU_INSTALL_ALWAYS_COPY> =back -=head2 ExtUtils::Installed - Inventory management of installed modules +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Installed, ExtUtils::Installed +- Inventory management of installed modules =over 4 @@ -21478,7 +22258,8 @@ packlist(), version() =back -=head2 ExtUtils::Liblist - determine libraries to use and how to use them +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Liblist, ExtUtils::Liblist - +determine libraries to use and how to use them =over 4 @@ -21513,7 +22294,8 @@ dynamic extensions at load time =back -=head2 ExtUtils::MM - OS adjusted ExtUtils::MakeMaker subclass +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM, ExtUtils::MM - OS adjusted +ExtUtils::MakeMaker subclass =over 4 @@ -21523,7 +22305,8 @@ dynamic extensions at load time =back -=head2 ExtUtils::MM_AIX - AIX specific subclass of ExtUtils::MM_Unix +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_AIX, ExtUtils::MM_AIX - AIX +specific subclass of ExtUtils::MM_Unix =over 4 @@ -21547,7 +22330,8 @@ dynamic extensions at load time =back -=head2 ExtUtils::MM_Any - Platform-agnostic MM methods +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_Any, ExtUtils::MM_Any - +Platform-agnostic MM methods =over 4 @@ -21601,8 +22385,8 @@ dynamic extensions at load time =back -=head2 ExtUtils::MM_BeOS - methods to override UN*X behaviour in -ExtUtils::MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_BeOS, ExtUtils::MM_BeOS - +methods to override UN*X behaviour in ExtUtils::MakeMaker =over 4 @@ -21616,8 +22400,8 @@ os_flavor init_linker -=head2 ExtUtils::MM_Cygwin - methods to override UN*X behaviour in -ExtUtils::MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_Cygwin, ExtUtils::MM_Cygwin +- methods to override UN*X behaviour in ExtUtils::MakeMaker =over 4 @@ -21637,7 +22421,12 @@ init_linker maybe_command -=head2 ExtUtils::MM_DOS - DOS specific subclass of ExtUtils::MM_Unix +dynamic_lib + +all_target + +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_DOS, ExtUtils::MM_DOS - DOS +specific subclass of ExtUtils::MM_Unix =over 4 @@ -21665,7 +22454,8 @@ B<replace_manpage_separator> =back -=head2 ExtUtils::MM_Darwin - special behaviors for OS X +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_Darwin, ExtUtils::MM_Darwin +- special behaviors for OS X =over 4 @@ -21681,7 +22471,8 @@ B<replace_manpage_separator> =back -=head2 ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_MacOS, ExtUtils::MM_MacOS - +once produced Makefiles for MacOS Classic =over 4 @@ -21691,8 +22482,8 @@ B<replace_manpage_separator> =back -=head2 ExtUtils::MM_NW5 - methods to override UN*X behaviour in -ExtUtils::MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_NW5, ExtUtils::MM_NW5 - +methods to override UN*X behaviour in ExtUtils::MakeMaker =over 4 @@ -21712,8 +22503,8 @@ static_lib dynamic_lib -=head2 ExtUtils::MM_OS2 - methods to override UN*X behaviour in -ExtUtils::MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_OS2, ExtUtils::MM_OS2 - +methods to override UN*X behaviour in ExtUtils::MakeMaker =over 4 @@ -21731,7 +22522,8 @@ init_linker os_flavor -=head2 ExtUtils::MM_QNX - QNX specific subclass of ExtUtils::MM_Unix +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_QNX, ExtUtils::MM_QNX - QNX +specific subclass of ExtUtils::MM_Unix =over 4 @@ -21755,7 +22547,8 @@ os_flavor =back -=head2 ExtUtils::MM_UWIN - U/WIN specific subclass of ExtUtils::MM_Unix +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_UWIN, ExtUtils::MM_UWIN - +U/WIN specific subclass of ExtUtils::MM_Unix =over 4 @@ -21783,7 +22576,8 @@ B<replace_manpage_separator> =back -=head2 ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_Unix, ExtUtils::MM_Unix - +methods used by ExtUtils::MakeMaker =over 4 @@ -21983,8 +22777,8 @@ xs_o (o) =back -=head2 ExtUtils::MM_VMS - methods to override UN*X behaviour in -ExtUtils::MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_VMS, ExtUtils::MM_VMS - +methods to override UN*X behaviour in ExtUtils::MakeMaker =over 4 @@ -22012,6 +22806,8 @@ guess_name (override) find_perl (override) +_fixin_replace_shebang (override) + maybe_command (override) pasthru (override) @@ -22102,7 +22898,8 @@ os_flavor =back -=head2 ExtUtils::MM_VOS - VOS specific subclass of ExtUtils::MM_Unix +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_VOS, ExtUtils::MM_VOS - VOS +specific subclass of ExtUtils::MM_Unix =over 4 @@ -22126,8 +22923,8 @@ os_flavor =back -=head2 ExtUtils::MM_Win32 - methods to override UN*X behaviour in -ExtUtils::MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_Win32, ExtUtils::MM_Win32 - +methods to override UN*X behaviour in ExtUtils::MakeMaker =over 4 @@ -22183,7 +22980,8 @@ os_flavor cflags -=head2 ExtUtils::MM_Win95 - method to customize MakeMaker for Win9X +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MM_Win95, ExtUtils::MM_Win95 - +method to customize MakeMaker for Win9X =over 4 @@ -22215,7 +23013,8 @@ os_flavor =back -=head2 ExtUtils::MY - ExtUtils::MakeMaker subclass for customization +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MY, ExtUtils::MY - +ExtUtils::MakeMaker subclass for customization =over 4 @@ -22225,7 +23024,8 @@ os_flavor =back -=head2 ExtUtils::MakeMaker - Create a module Makefile +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MakeMaker, ExtUtils::MakeMaker +- Create a module Makefile =over 4 @@ -22272,13 +23072,14 @@ 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, 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_DIR, 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 +NEEDS_LINKING, NOECHO, NORECURS, NO_META, NO_MYMETA, NO_VC, OBJECT, +OPTIMIZE, PERL, PERL_CORE, PERLMAINCC, PERL_ARCHLIB, PERL_LIB, +PERL_MALLOC_OK, PERLPREFIX, PERLRUN, PERLRUNINST, PERL_SRC, PERM_DIR, +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 @@ -22321,7 +23122,8 @@ PERL_MM_OPT, PERL_MM_USE_DEFAULT, PERL_CORE =back -=head2 ExtUtils::MakeMaker::Config - Wrapper around Config.pm +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MakeMaker::Config, +ExtUtils::MakeMaker::Config - Wrapper around Config.pm =over 4 @@ -22331,8 +23133,8 @@ PERL_MM_OPT, PERL_MM_USE_DEFAULT, PERL_CORE =back -=head2 ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About -MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MakeMaker::FAQ, +ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker =over 4 @@ -22357,8 +23159,8 @@ shell commands, easier to customize, cleaner internals, less cruft How do I keep my $VERSION up to date without resetting it manually?, What's this F<META.yml> thing and how did it get in my F<MANIFEST>?!, How do I -delete everything not in my F<MANIFEST>?, Which zip should I use on Windows -for '[nd]make zipdist'? +delete everything not in my F<MANIFEST>?, Which tar should I use on +Windows?, Which zip should I use on Windows for '[nd]make zipdist'? =item XS @@ -22376,7 +23178,8 @@ directory? =back -=head2 ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MakeMaker::Tutorial, +ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker =over 4 @@ -22399,7 +23202,23 @@ bin/ =back -=head2 ExtUtils::Manifest - utilities to write and check a MANIFEST file +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::MakeMaker::YAML, +ExtUtils::MakeMaker::YAML - clone of YAML::Tiny + +=over 4 + +=item SYNOPSIS + +=item AUTHOR + +=item SEE ALSO + +=item COPYRIGHT + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Manifest, ExtUtils::Manifest - +utilities to write and check a MANIFEST file =over 4 @@ -22466,7 +23285,8 @@ B<PERL_MM_MANIFEST_DEBUG> =back -=head2 ExtUtils::Miniperl, writemain - write the C code for perlmain.c +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Miniperl, ExtUtils::Miniperl, +writemain - write the C code for perlmain.c =over 4 @@ -22478,7 +23298,8 @@ B<PERL_MM_MANIFEST_DEBUG> =back -=head2 ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Mkbootstrap, +ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader =over 4 @@ -22488,8 +23309,8 @@ B<PERL_MM_MANIFEST_DEBUG> =back -=head2 ExtUtils::Mksymlists - write linker options files for dynamic -extension +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Mksymlists, +ExtUtils::Mksymlists - write linker options files for dynamic extension =over 4 @@ -22509,7 +23330,8 @@ mkfh() __find_relocations -=head2 ExtUtils::Packlist - manage .packlist files +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::Packlist, ExtUtils::Packlist - +manage .packlist files =over 4 @@ -22529,7 +23351,8 @@ new(), read(), write(), validate(), packlist_file() =back -=head2 ExtUtils::ParseXS - converts Perl XS code into C code +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::ParseXS, ExtUtils::ParseXS - +converts Perl XS code into C code =over 4 @@ -22551,8 +23374,8 @@ errors() =back -=head2 ExtUtils::XSSymSet - keep sets of symbol names palatable to the VMS -linker +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::XSSymSet, ExtUtils::XSSymSet - +keep sets of symbol names palatable to the VMS linker =over 4 @@ -22570,7 +23393,8 @@ get_trimmed($name), all_orig(), all_trimmed() =back -=head2 ExtUtils::testlib - add blib/* directories to @INC +=head2 C:\perl_tl\perl-5.14.2\lib::ExtUtils::testlib, ExtUtils::testlib - +add blib/* directories to @INC =over 4 @@ -22580,7 +23404,8 @@ get_trimmed($name), all_orig(), all_trimmed() =back -=head2 Fatal - Replace functions with equivalents which succeed or die +=head2 C:\perl_tl\perl-5.14.2\lib::Fatal, Fatal - Replace functions with +equivalents which succeed or die =over 4 @@ -22606,7 +23431,8 @@ neither a builtin, nor a Perl subroutine, Cannot make the non-overridable =back -=head2 Fcntl - load the C Fcntl.h defines +=head2 C:\perl_tl\perl-5.14.2\lib::Fcntl, Fcntl - load the C Fcntl.h +defines =over 4 @@ -22620,40 +23446,8 @@ neither a builtin, nor a Perl subroutine, Cannot make the non-overridable =back -=head2 File-Glob, File::Glob - Perl extension for BSD glob routine - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item META CHARACTERS - -=item POSIX FLAGS - -C<GLOB_ERR>, C<GLOB_LIMIT>, C<GLOB_MARK>, C<GLOB_NOCASE>, C<GLOB_NOCHECK>, -C<GLOB_NOSORT>, C<GLOB_BRACE>, C<GLOB_NOMAGIC>, C<GLOB_QUOTE>, -C<GLOB_TILDE>, C<GLOB_CSH>, C<GLOB_ALPHASORT> - -=back - -=item DIAGNOSTICS - -C<GLOB_NOSPACE>, C<GLOB_ABEND> - -=item NOTES - -=item SEE ALSO - -=item AUTHOR - -=back - -=head2 File::Basename - Parse file paths into directory, filename and -suffix. +=head2 C:\perl_tl\perl-5.14.2\lib::File::Basename, File::Basename - Parse +file paths into directory, filename and suffix. =over 4 @@ -22677,7 +23471,8 @@ C<fileparse_set_fstype> X<filesystem> =back -=head2 File::CheckTree - run many filetest checks on a tree +=head2 C:\perl_tl\perl-5.14.2\lib::File::CheckTree, File::CheckTree - run +many filetest checks on a tree =over 4 @@ -22691,7 +23486,8 @@ C<fileparse_set_fstype> X<filesystem> =back -=head2 File::Compare - Compare files or filehandles +=head2 C:\perl_tl\perl-5.14.2\lib::File::Compare, File::Compare - Compare +files or filehandles =over 4 @@ -22705,7 +23501,8 @@ C<fileparse_set_fstype> X<filesystem> =back -=head2 File::Copy - Copy files or filehandles +=head2 C:\perl_tl\perl-5.14.2\lib::File::Copy, File::Copy - Copy files or +filehandles =over 4 @@ -22718,13 +23515,12 @@ rmscopy($from,$to[,$date_flag]) X<rmscopy> =item RETURN -=item NOTES - =item AUTHOR =back -=head2 File::DosGlob - DOS like globbing and then some +=head2 C:\perl_tl\perl-5.14.2\lib::File::DosGlob, File::DosGlob - DOS like +globbing and then some =over 4 @@ -22732,8 +23528,6 @@ rmscopy($from,$to[,$date_flag]) X<rmscopy> =item DESCRIPTION -=item NOTES - =item EXPORTS (by request only) =item BUGS @@ -22746,7 +23540,8 @@ rmscopy($from,$to[,$date_flag]) X<rmscopy> =back -=head2 File::Fetch - A generic file fetching mechanism +=head2 C:\perl_tl\perl-5.14.2\lib::File::Fetch, File::Fetch - A generic +file fetching mechanism =over 4 @@ -22841,7 +23636,8 @@ Implement $PREFER_BIN =back -=head2 File::Find - Traverse a directory tree. +=head2 C:\perl_tl\perl-5.14.2\lib::File::Find, File::Find - Traverse a +directory tree. =over 4 @@ -22873,8 +23669,6 @@ pathname to the file $dont_use_nlink, symlinks -=item NOTES - =item BUGS AND CAVEATS =item HISTORY @@ -22883,7 +23677,8 @@ $dont_use_nlink, symlinks =back -=head2 File::Glob - Perl extension for BSD glob routine +=head2 C:\perl_tl\perl-5.14.2\lib::File::Glob, File::Glob - Perl extension +for BSD glob routine =over 4 @@ -22915,7 +23710,8 @@ C<GLOB_NOSPACE>, C<GLOB_ABEND> =back -=head2 File::GlobMapper - Extend File Glob to Allow Input and Output Files +=head2 C:\perl_tl\perl-5.14.2\lib::File::GlobMapper, File::GlobMapper - +Extend File Glob to Allow Input and Output Files =over 4 @@ -22959,7 +23755,8 @@ B<~>, B<~user>, B<.>, B<*>, B<?>, B<\>, B<[]>, B<{,}>, B<()> =back -=head2 File::Path - Create or remove directory trees +=head2 C:\perl_tl\perl-5.14.2\lib::File::Path, File::Path - Create or +remove directory trees =over 4 @@ -23023,7 +23820,8 @@ group ownership not changed =back -=head2 File::Spec - portably perform operations on file names +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec, File::Spec - portably +perform operations on file names =over 4 @@ -23048,7 +23846,8 @@ X<relative, path>, rel2abs() X<rel2abs> X<absolute, path> X<relative, path> =back -=head2 File::Spec::Cygwin - methods for Cygwin file specs +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec::Cygwin, File::Spec::Cygwin - +methods for Cygwin file specs =over 4 @@ -23072,7 +23871,8 @@ case_tolerant =back -=head2 File::Spec::Epoc - methods for Epoc file specs +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec::Epoc, File::Spec::Epoc - +methods for Epoc file specs =over 4 @@ -23094,7 +23894,8 @@ canonpath() =back -=head2 File::Spec::Functions - portably perform operations on file names +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec::Functions, +File::Spec::Functions - portably perform operations on file names =over 4 @@ -23114,7 +23915,8 @@ canonpath() =back -=head2 File::Spec::Mac - File::Spec for Mac OS (Classic) +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec::Mac, File::Spec::Mac - +File::Spec for Mac OS (Classic) =over 4 @@ -23166,7 +23968,8 @@ rel2abs =back -=head2 File::Spec::OS2 - methods for OS/2 file specs +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec::OS2, File::Spec::OS2 - +methods for OS/2 file specs =over 4 @@ -23180,8 +23983,8 @@ tmpdir, splitpath =back -=head2 File::Spec::Unix - File::Spec for Unix, base for other File::Spec -modules +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec::Unix, File::Spec::Unix - +File::Spec for Unix, base for other File::Spec modules =over 4 @@ -23237,7 +24040,8 @@ rel2abs() =back -=head2 File::Spec::VMS - methods for VMS file specs +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec::VMS, File::Spec::VMS - +methods for VMS file specs =over 4 @@ -23287,7 +24091,8 @@ rel2abs (override) =back -=head2 File::Spec::Win32 - methods for Win32 file specs +=head2 C:\perl_tl\perl-5.14.2\lib::File::Spec::Win32, File::Spec::Win32 - +methods for Win32 file specs =over 4 @@ -23329,7 +24134,8 @@ catpath =back -=head2 File::Temp - return name and handle of a temporary file safely +=head2 C:\perl_tl\perl-5.14.2\lib::File::Temp, File::Temp - return name and +handle of a temporary file safely =over 4 @@ -23449,7 +24255,8 @@ B<$KEEP_ALL>, B<$DEBUG> =back -=head2 File::stat - by-name interface to Perl's built-in stat() functions +=head2 C:\perl_tl\perl-5.14.2\lib::File::stat, File::stat - by-name +interface to Perl's built-in stat() functions =over 4 @@ -23473,24 +24280,8 @@ File::stat ignores use filetest 'access', File::stat ignores VMS ACLs =back -=head2 FileCache - keep more files open than the system permits - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -cacheout EXPR, cacheout MODE, EXPR - -=item CAVEATS - -=item BUGS - -=back - -=head2 FileCache::lib::FileCache, FileCache - keep more files open than the -system permits +=head2 C:\perl_tl\perl-5.14.2\lib::FileCache, FileCache - keep more files +open than the system permits =over 4 @@ -23506,7 +24297,8 @@ cacheout EXPR, cacheout MODE, EXPR =back -=head2 FileHandle - supply object methods for filehandles +=head2 C:\perl_tl\perl-5.14.2\lib::FileHandle, FileHandle - supply object +methods for filehandles =over 4 @@ -23520,7 +24312,8 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =back -=head2 Filter::Simple - Simplified source filtering +=head2 C:\perl_tl\perl-5.14.2\lib::Filter::Simple, Filter::Simple - +Simplified source filtering =over 4 @@ -23546,11 +24339,6 @@ C<"all"> =item Filtering only the code parts of source code -Most source code ceases to be grammatically correct when it is broken up -into the pieces between string literals and regexes. So the C<'code'> -and C<'code_no_comments'> component filter behave slightly differently -from the other partial filters described in the previous section. - =item Using Filter::Simple with an explicit C<import> subroutine =item Using Filter::Simple and Exporter together @@ -23567,7 +24355,8 @@ from the other partial filters described in the previous section. =back -=head2 Filter::Util::Call - Perl Source Filter Utility Module +=head2 C:\perl_tl\perl-5.14.2\lib::Filter::Util::Call, Filter::Util::Call - +Perl Source Filter Utility Module =over 4 @@ -23609,7 +24398,8 @@ B<$_>, B<$status>, B<filter_read> and B<filter_read_exact>, B<filter_del> =back -=head2 FindBin - Locate directory of original perl script +=head2 C:\perl_tl\perl-5.14.2\lib::FindBin, FindBin - Locate directory of +original perl script =over 4 @@ -23629,23 +24419,8 @@ B<$_>, B<$status>, B<filter_read> and B<filter_read_exact>, B<filter_del> =back -=head2 GDBM_File - Perl5 access to the gdbm library. - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item AVAILABILITY - -=item BUGS - -=item SEE ALSO - -=back - -=head2 Getopt::Long - Extended processing of command line options +=head2 C:\perl_tl\perl-5.14.2\lib::Getopt::Long, Getopt::Long - Extended +processing of command line options =over 4 @@ -23764,8 +24539,8 @@ supplied =back -=head2 Getopt::Std, getopt, getopts - Process single-character switches -with switch clustering +=head2 C:\perl_tl\perl-5.14.2\lib::Getopt::Std, getopt, getopts - Process +single-character switches with switch clustering =over 4 @@ -23777,126 +24552,53 @@ with switch clustering =back -=head2 Hash-Util-FieldHash::lib::Hash::Util::FieldHash, -Hash::Util::FieldHash - Support for Inside-Out Classes +=head2 C:\perl_tl\perl-5.14.2\lib::HTTP::Tiny, HTTP::Tiny - A small, +simple, correct HTTP/1.1 client =over 4 -=item SYNOPSIS - -=item FUNCTIONS +=item VERSION -id, id_2obj, register, idhash, idhashes, fieldhash, fieldhashes +=item SYNOPSIS =item DESCRIPTION -=over 4 - -=item The Inside-out Technique - -=item Problems of Inside-out - -=item Solutions - -=item More Problems - -=item The Generic Object - -=item How to use Field Hashes - -=item Garbage-Collected Hashes - -=back - -=item EXAMPLES - -C<init()>, C<first()>, C<last()>, C<name()>, C<Name_hash>, C<Name_id>, -C<Name_idhash>, C<Name_id_reg>, C<Name_idhash_reg>, C<Name_fieldhash> - -=over 4 - -=item Example 1 - -=item Example 2 - -=back - -=item GUTS - -=over 4 - -=item The C<PERL_MAGIC_uvar> interface for hashes - -=item Weakrefs call uvar magic - -=item How field hashes work - -=item Internal function Hash::Util::FieldHash::_fieldhash - -=back - -=item AUTHOR - -=item COPYRIGHT AND LICENSE - -=back - -=head2 Hash-Utilib::Hash::Util, Hash::Util - A selection of general-utility -hash subroutines +=item METHODS =over 4 -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 +=item new -=item Restricted hashes +=item get -B<lock_keys>, B<unlock_keys> +=item mirror -=back +=item request =back -B<lock_keys_plus> - -B<lock_value>, B<unlock_value> - -B<lock_hash>, B<unlock_hash> - -B<lock_hash_recurse>, B<unlock_hash_recurse> - -B<hash_unlocked> +=item LIMITATIONS -B<legal_keys>, B<hidden_keys>, B<all_keys>, B<hash_seed> +=item SEE ALSO -B<hv_store> +=item SUPPORT =over 4 -=item Operating on references to hashes. +=item Bugs / Feature Requests -lock_ref_keys, unlock_ref_keys, lock_ref_keys_plus, lock_ref_value, -unlock_ref_value, lock_hashref, unlock_hashref, lock_hashref_recurse, -unlock_hashref_recurse, hash_ref_unlocked, legal_ref_keys, hidden_ref_keys +=item Source Code =back -=over 4 - -=item CAVEATS - -=item BUGS - -=item AUTHOR +=item AUTHORS -=item SEE ALSO +=item COPYRIGHT AND LICENSE =back -=head2 Hash::Util - A selection of general-utility hash subroutines +=head2 C:\perl_tl\perl-5.14.2\lib::Hash::Util, Hash::Util - A selection of +general-utility hash subroutines =over 4 @@ -23950,7 +24652,8 @@ unlock_hashref_recurse, hash_ref_unlocked, legal_ref_keys, hidden_ref_keys =back -=head2 Hash::Util::FieldHash - Support for Inside-Out Classes +=head2 C:\perl_tl\perl-5.14.2\lib::Hash::Util::FieldHash, +Hash::Util::FieldHash - Support for Inside-Out Classes =over 4 @@ -24013,7 +24716,8 @@ C<Name_idhash>, C<Name_id_reg>, C<Name_idhash_reg>, C<Name_fieldhash> =back -=head2 I18N-Langinfo, I18N::Langinfo - query locale information +=head2 C:\perl_tl\perl-5.14.2\lib::I18N::Collate, I18N::Collate - compare +8-bit scalar data according to the current locale =over 4 @@ -24021,33 +24725,10 @@ C<Name_idhash>, C<Name_id_reg>, C<Name_idhash_reg>, C<Name_fieldhash> =item DESCRIPTION -=over 4 - -=item EXPORT - =back -=item SEE ALSO - -=item AUTHOR - -=item COPYRIGHT AND LICENSE - -=back - -=head2 I18N::Collate - compare 8-bit scalar data according to the current -locale - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=back - -=head2 I18N::LangTags - functions for dealing with RFC3066-style language -tags +=head2 C:\perl_tl\perl-5.14.2\lib::I18N::LangTags, I18N::LangTags - +functions for dealing with RFC3066-style language tags =over 4 @@ -24094,7 +24775,8 @@ implicate_supers_strictly( ...languages... ) =back -=head2 I18N::LangTags::Detect - detect the user's language preferences +=head2 C:\perl_tl\perl-5.14.2\lib::I18N::LangTags::Detect, +I18N::LangTags::Detect - detect the user's language preferences =over 4 @@ -24114,7 +24796,8 @@ implicate_supers_strictly( ...languages... ) =back -=head2 I18N::LangTags::List -- tags and names for human languages +=head2 C:\perl_tl\perl-5.14.2\lib::I18N::LangTags::List, +I18N::LangTags::List -- tags and names for human languages =over 4 @@ -24262,7 +24945,7 @@ Sichuan Yi, {yi} : Yiddish, {yo} : Yoruba, [{ypk} : Yupik languages], {znd} =back -=head2 IO - load various IO modules +=head2 C:\perl_tl\perl-5.14.2\lib::IO, IO - load various IO modules =over 4 @@ -24274,7 +24957,8 @@ Sichuan Yi, {yi} : Yiddish, {yo} : Yoruba, [{ypk} : Yupik languages], {znd} =back -=head2 IO::Compress::Base - Base Class for IO::Compress modules +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Compress::Base, IO::Compress::Base - +Base Class for IO::Compress modules =over 4 @@ -24292,7 +24976,8 @@ Sichuan Yi, {yi} : Yiddish, {yo} : Yoruba, [{ypk} : Yupik languages], {znd} =back -=head2 IO::Compress::Bzip2 - Write bzip2 files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Compress::Bzip2, IO::Compress::Bzip2 +- Write bzip2 files/buffers =over 4 @@ -24398,7 +25083,8 @@ C<< Strict => 0|1 >> =back -=head2 IO::Compress::Deflate - Write RFC 1950 files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Compress::Deflate, +IO::Compress::Deflate - Write RFC 1950 files/buffers =over 4 @@ -24506,7 +25192,8 @@ Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >> =back -=head2 IO::Compress::Gzip - Write RFC 1952 files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Compress::Gzip, IO::Compress::Gzip - +Write RFC 1952 files/buffers =over 4 @@ -24618,7 +25305,8 @@ C<< ExtraField => $data >>, C<< ExtraFlags => $value >>, C<< Strict => 0|1 =back -=head2 IO::Compress::RawDeflate - Write RFC 1951 files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Compress::RawDeflate, +IO::Compress::RawDeflate - Write RFC 1951 files/buffers =over 4 @@ -24726,7 +25414,8 @@ Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >> =back -=head2 IO::Compress::Zip - Write zip files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Compress::Zip, IO::Compress::Zip - +Write zip files/buffers =over 4 @@ -24841,7 +25530,8 @@ number >>, C<< WorkFactor => number >>, -Level, -Strategy, C<< Strict => =back -=head2 IO::Dir - supply object methods for directory handles +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Dir, IO::Dir - supply object methods +for directory handles =over 4 @@ -24860,7 +25550,8 @@ rewind (), close (), tie %hash, 'IO::Dir', DIRNAME [, OPTIONS ] =back -=head2 IO::File - supply object methods for filehandles +=head2 C:\perl_tl\perl-5.14.2\lib::IO::File, IO::File - supply object +methods for filehandles =over 4 @@ -24885,7 +25576,8 @@ open( FILENAME [,MODE [,PERMS]] ), open( FILENAME, IOLAYERS ), binmode( =back -=head2 IO::Handle - supply object methods for I/O handles +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Handle, IO::Handle - supply object +methods for I/O handles =over 4 @@ -24914,7 +25606,8 @@ $io->blocking ( [ BOOL ] ), $io->untaint =back -=head2 IO::Pipe - supply object methods for pipes +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Pipe, IO::Pipe - supply object +methods for pipes =over 4 @@ -24938,7 +25631,8 @@ reader ([ARGS]), writer ([ARGS]), handles () =back -=head2 IO::Poll - Object interface to system poll call +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Poll, IO::Poll - Object interface to +system poll call =over 4 @@ -24959,7 +25653,8 @@ IO ), handles( [ EVENT_MASK ] ) =back -=head2 IO::Seekable - supply seek based methods for I/O objects +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Seekable, IO::Seekable - supply seek +based methods for I/O objects =over 4 @@ -24977,7 +25672,8 @@ $io->tell =back -=head2 IO::Select - OO interface to the select system call +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Select, IO::Select - OO interface to +the select system call =over 4 @@ -25003,7 +25699,8 @@ count (), bits(), select ( READ, WRITE, EXCEPTION [, TIMEOUT ] ) =back -=head2 IO::Socket - Object interface to socket communications +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Socket, IO::Socket - Object +interface to socket communications =over 4 @@ -25029,7 +25726,8 @@ setsockopt(LEVEL, OPT, VAL), socktype, timeout([VAL]) =back -=head2 IO::Socket::INET - Object interface for AF_INET domain sockets +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Socket::INET, IO::Socket::INET - +Object interface for AF_INET domain sockets =over 4 @@ -25058,7 +25756,8 @@ sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost =back -=head2 IO::Socket::UNIX - Object interface for AF_UNIX domain sockets +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Socket::UNIX, IO::Socket::UNIX - +Object interface for AF_UNIX domain sockets =over 4 @@ -25082,8 +25781,8 @@ hostpath(), peerpath() =back -=head2 IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip) -file/buffer +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Uncompress::AnyInflate, +IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip) file/buffer =over 4 @@ -25200,7 +25899,8 @@ the sub-field structure as defined in RFC 1952 =back -=head2 IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Uncompress::AnyUncompress, +IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop file/buffer =over 4 @@ -25309,7 +26009,8 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< RawInflate => 0|1 =back -=head2 IO::Uncompress::Base - Base Class for IO::Uncompress modules +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Uncompress::Base, +IO::Uncompress::Base - Base Class for IO::Uncompress modules =over 4 @@ -25327,7 +26028,8 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< RawInflate => 0|1 =back -=head2 IO::Uncompress::Bunzip2 - Read bzip2 files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Uncompress::Bunzip2, +IO::Uncompress::Bunzip2 - Read bzip2 files/buffers =over 4 @@ -25436,7 +26138,8 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< Small => 0|1 >> =back -=head2 IO::Uncompress::Gunzip - Read RFC 1952 files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Uncompress::Gunzip, +IO::Uncompress::Gunzip - Read RFC 1952 files/buffers =over 4 @@ -25553,7 +26256,8 @@ Name, Comment =back -=head2 IO::Uncompress::Inflate - Read RFC 1950 files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Uncompress::Inflate, +IO::Uncompress::Inflate - Read RFC 1950 files/buffers =over 4 @@ -25665,7 +26369,8 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =back -=head2 IO::Uncompress::RawInflate - Read RFC 1951 files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Uncompress::RawInflate, +IO::Uncompress::RawInflate - Read RFC 1951 files/buffers =over 4 @@ -25777,7 +26482,8 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =back -=head2 IO::Uncompress::Unzip - Read zip files/buffers +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Uncompress::Unzip, +IO::Uncompress::Unzip - Read zip files/buffers =over 4 @@ -25817,9 +26523,10 @@ A filename, A filehandle, A scalar reference =item Constructor Options -C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string ->>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength => -$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> +C<< Name => "membername" >>, C<< AutoClose => 0|1 >>, C<< MultiStream => +0|1 >>, C<< Prime => $string >>, C<< Transparent => 0|1 >>, C<< BlockSize +=> $num >>, C<< InputLength => $size >>, C<< Append => 0|1 >>, C<< Strict +=> 0|1 >> =item Examples @@ -25877,6 +26584,8 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =item Working with Net::FTP +=item Walking through a zip file + =back =item SEE ALSO @@ -25889,7 +26598,8 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =back -=head2 IO::Zlib - IO:: style interface to L<Compress::Zlib> +=head2 C:\perl_tl\perl-5.14.2\lib::IO::Zlib, IO::Zlib - IO:: style +interface to L<Compress::Zlib> =over 4 @@ -25934,8 +26644,8 @@ IO::Zlib::WRITE: too long LENGTH =back -=head2 IPC-Open2::lib::IPC::Open2, IPC::Open2 - open a process for both -reading and writing using open2() +=head2 C:\perl_tl\perl-5.14.2\lib::IPC::Cmd, IPC::Cmd - finding and running +system commands made easy =over 4 @@ -25943,31 +26653,113 @@ reading and writing using open2() =item DESCRIPTION -=item WARNING +=item CLASS METHODS -=item SEE ALSO +=over 4 + +=item $ipc_run_version = IPC::Cmd->can_use_ipc_run( [VERBOSE] ) =back -=head2 IPC-Open3::lib::IPC::Open3, IPC::Open3 - open a process for reading, -writing, and error handling using open3() +=back =over 4 -=item SYNOPSIS +=item $ipc_open3_version = IPC::Cmd->can_use_ipc_open3( [VERBOSE] ) -=item DESCRIPTION +=back + +=over 4 + +=item $bool = IPC::Cmd->can_capture_buffer + +=back + +=over 4 + +=item $bool = IPC::Cmd->can_use_run_forked + +=back + +=over 4 + +=item FUNCTIONS + +=over 4 + +=item $path = can_run( PROGRAM ); + +=back + +=back + +=over 4 + +=item $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( +command => COMMAND, [verbose => BOOL, buffer => \$SCALAR, timeout => DIGIT] +); + +command, verbose, buffer, timeout, success, error message, full_buffer, +out_buffer, error_buffer + +=back + +=over 4 + +=item $hashref = run_forked( COMMAND, { child_stdin => SCALAR, timeout => +DIGIT, stdout_handler => CODEREF, stderr_handler => CODEREF} ); + +C<timeout>, C<child_stdin>, C<stdout_handler>, C<stderr_handler>, +C<discard_output>, C<terminate_on_parent_sudden_death>, C<exit_code>, +C<timeout>, C<stdout>, C<stderr>, C<merged>, C<err_msg> + +=back + +=over 4 + +=item $q = QUOTE + +=back + +=over 4 + +=item HOW IT WORKS + +=item Global Variables + +=over 4 + +=item $IPC::Cmd::VERBOSE + +=item $IPC::Cmd::USE_IPC_RUN + +=item $IPC::Cmd::USE_IPC_OPEN3 + +=item $IPC::Cmd::WARN + +=item $IPC::Cmd::INSTANCES + +=back + +=item Caveats + +Whitespace and IPC::Open3 / system(), Whitespace and IPC::Run, IO Redirect, +Interleaving STDOUT/STDERR =item See Also -L<IPC::Open2>, L<IPC::Run> +=item ACKNOWLEDGEMENTS -=item WARNING +=item BUG REPORTS + +=item AUTHOR + +=item COPYRIGHT =back -=head2 IPC::Open2 - open a process for both reading and writing using -open2() +=head2 C:\perl_tl\perl-5.14.2\lib::IPC::Open2, IPC::Open2 - open a process +for both reading and writing using open2() =over 4 @@ -25981,8 +26773,8 @@ open2() =back -=head2 IPC::Open3 - open a process for reading, writing, and error handling -using open3() +=head2 C:\perl_tl\perl-5.14.2\lib::IPC::Open3, IPC::Open3 - open a process +for reading, writing, and error handling using open3() =over 4 @@ -25998,117 +26790,197 @@ L<IPC::Open2>, L<IPC::Run> =back -=head2 IPCmd, IPC::Cmd - finding and running system commands made easy +=head2 C:\perl_tl\perl-5.14.2\lib::JSON::PP, JSON::PP - JSON::XS compatible +pure-Perl module. =over 4 =item SYNOPSIS -=item DESCRIPTION +=item VERSION -=item CLASS METHODS +=item NOTE + +=item DESCRIPTION =over 4 -=item $ipc_run_version = IPC::Cmd->can_use_ipc_run( [VERBOSE] ) +=item FEATURES -=back +correct unicode handling, round-trip integrity, strict checking of JSON +correctness =back +=item FUNCTIONAL INTERFACE + =over 4 -=item $ipc_open3_version = IPC::Cmd->can_use_ipc_open3( [VERBOSE] ) +=item encode_json -=back +=item decode_json -=over 4 +=item JSON::PP::is_bool -=item $bool = IPC::Cmd->can_capture_buffer +=item JSON::PP::true + +=item JSON::PP::false + +=item JSON::PP::null =back +=item HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER + +=item METHODS + =over 4 -=item $bool = IPC::Cmd->can_use_run_forked +=item new -=back +=item ascii -=over 4 +=item latin1 -=item FUNCTIONS +=item utf8 -=over 4 +=item pretty -=item $path = can_run( PROGRAM ); +=item indent -=back +=item space_before + +=item space_after + +=item relaxed + +list items can have an end-comma, shell-style '#'-comments + +=item canonical + +=item allow_nonref + +=item allow_unknown + +=item allow_blessed + +=item convert_blessed + +=item filter_json_object + +=item filter_json_single_key_object + +=item shrink + +=item max_depth + +=item max_size + +=item encode + +=item decode + +=item decode_prefix =back +=item INCREMENTAL PARSING + =over 4 -=item $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( -command => COMMAND, [verbose => BOOL, buffer => \$SCALAR, timeout => DIGIT] -); +=item incr_parse -command, verbose, buffer, timeout, success, error message, full_buffer, -out_buffer, error_buffer +=item incr_text + +=item incr_skip + +=item incr_reset =back +=item JSON::PP OWN METHODS + =over 4 -=item $hashref = run_forked( command => COMMAND, { child_stdin => SCALAR, -timeout => DIGIT, stdout_handler => CODEREF, stderr_handler => CODEREF} ); +=item allow_singlequote -C<timeout>, C<child_stdin>, C<stdout_handler>, C<stderr_handler>, -C<exit_code>, C<timeout>, C<stdout>, C<stderr>, C<merged>, C<err_msg> +=item allow_barekey + +=item allow_bignum + +=item loose + +=item escape_slash + +=item indent_length + +=item sort_by =back +=item INTERNAL + +PP_encode_box, PP_decode_box + +=item MAPPING + =over 4 -=item $q = QUOTE +=item JSON -> PERL + +object, array, string, number, true, false, null + +=item PERL -> JSON + +hash references, array references, other references, JSON::PP::true, +JSON::PP::false, JSON::PP::null, blessed objects, simple scalars, Big +Number =back +=item UNICODE HANDLING ON PERLS + =over 4 -=item HOW IT WORKS +=item Perl 5.8 and later -=item Global Variables +=item Perl 5.6 -=over 4 +=item Perl 5.005 -=item $IPC::Cmd::VERBOSE +=back -=item $IPC::Cmd::USE_IPC_RUN +=item TODO -=item $IPC::Cmd::USE_IPC_OPEN3 +speed, memory saving -=item $IPC::Cmd::WARN +=item SEE ALSO + +=item AUTHOR + +=item COPYRIGHT AND LICENSE =back -=item Caveats +=head2 C:\perl_tl\perl-5.14.2\lib::JSON::PP::Boolean, JSON::PP::Boolean - +dummy module providing JSON::PP::Boolean -Whitespace and IPC::Open3 / system(), Whitespace and IPC::Run, IO Redirect, -Interleaving STDOUT/STDERR +=over 4 -=item See Also +=item SYNOPSIS -=item ACKNOWLEDGEMENTS +=item DESCRIPTION -=item BUG REPORTS +=back -=item AUTHOR +=over 4 -=item COPYRIGHT +=item AUTHOR =back -=head2 List::Util - A selection of general-utility list subroutines +=head2 C:\perl_tl\perl-5.14.2\lib::List::Util, List::Util - A selection of +general-utility list subroutines =over 4 @@ -26129,8 +27001,8 @@ BLOCK LIST, shuffle LIST, sum LIST =back -=head2 List::Util::XS - Indicate if List::Util was compiled with a C -compiler +=head2 C:\perl_tl\perl-5.14.2\lib::List::Util::XS, List::Util::XS - +Indicate if List::Util was compiled with a C compiler =over 4 @@ -26144,19 +27016,80 @@ compiler =back -=head2 Locale::Constants - constants for Locale codes +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Codes, Locale::Codes - a +distribution of modules to handle locale codes =over 4 -=item SYNOPSIS - =item DESCRIPTION +B<Locale::Country>, B<Locale::Language>, B<Locale::Currency>, +B<Locale::Script> + +=item NEW CODE SETS + +B<General-use code set>, B<An official source of data>, B<A free source of +the data>, B<A reliable source of data> + +=item COMMON ALIASES + +=item ROUTINES + +B<code2country ( CODE [,CODESET] )>, B<code2language( CODE [,CODESET] )>, +B<code2currency( CODE [,CODESET] )>, B<code2script ( CODE [,CODESET] )>, +B<country2code ( NAME [,CODESET] )>, B<language2code( NAME [,CODESET] )>, +B<currency2code( NAME [,CODESET] )>, B<script2code ( NAME [,CODESET] )>, +B<country_code2code ( CODE ,CODESET ,CODESET2 )>, B<language_code2code( +CODE ,CODESET ,CODESET2 )>, B<currency_code2code( CODE ,CODESET ,CODESET2 +)>, B<script_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_country_codes ( +[CODESET] )>, B<all_language_codes( [CODESET] )>, B<all_currency_codes( +[CODESET] )>, B<all_script_codes ( [CODESET] )>, B<all_country_names ( +[CODESET] )>, B<all_language_names( [CODESET] )>, B<all_currency_names( +[CODESET] )>, B<all_script_names ( [CODESET] )> + +=item SEMI-PRIVATE ROUTINES + +B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )>, +B<Locale::Language::rename_language( CODE ,NEW_NAME [,CODESET] )>, +B<Locale::Currency::rename_currency( CODE ,NEW_NAME [,CODESET] )>, +B<Locale::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )>, +B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )>, +B<Locale::Language::add_language( CODE ,NAME [,CODESET] )>, +B<Locale::Currency::add_currency( CODE ,NAME [,CODESET] )>, +B<Locale::Script::add_script ( CODE ,NAME [,CODESET] )>, +B<Locale::Country::delete_country ( CODE [,CODESET] )>, +B<Locale::Language::delete_language( CODE [,CODESET] )>, +B<Locale::Currency::delete_currency( CODE [,CODESET] )>, +B<Locale::Script::delete_script ( CODE [,CODESET] )>, +B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )>, +B<Locale::Language::add_language_alias( NAME ,NEW_NAME )>, +B<Locale::Currency::add_currency_alias( NAME ,NEW_NAME )>, +B<Locale::Script::add_script_alias ( NAME ,NEW_NAME )>, +B<Locale::Country::delete_country_alias ( NAME )>, +B<Locale::Language::delete_language_alias( NAME )>, +B<Locale::Currency::delete_currency_alias( NAME )>, +B<Locale::Script::delete_script_alias ( NAME )>, +B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Language::rename_language_code( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Currency::rename_currency_code( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Language::add_language_code_alias( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Currency::add_currency_code_alias( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )>, +B<Locale::Language::delete_language_code_alias( CODE [,CODESET] )>, +B<Locale::Currency::delete_currency_code_alias( CODE [,CODESET] )>, +B<Locale::Script::delete_script_code_alias ( CODE [,CODESET] )> + =item KNOWN BUGS AND LIMITATIONS +B<*>, B<*> + =item SEE ALSO -Locale::Language, Locale::Country, Locale::Script, Locale::Currency +B<Locale::Constants>, B<Locale::Country>, B<Locale::Language>, +B<Locale::Script>, B<Locale::Currency> =item AUTHOR @@ -26164,47 +27097,62 @@ Locale::Language, Locale::Country, Locale::Script, Locale::Currency =back -=head2 Locale::Country - ISO codes for country identification (ISO 3166) +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Codes::Changes, +Locale::Codes::Changes - details important changes after 2.07 =over 4 -=item SYNOPSIS +=item 3.10 -=item DESCRIPTION +B<Changed XXX_code2code behavior slightly>, B<Added many semi-private +routines> + +=item 3.00 -B<alpha-2>, B<alpha-3>, B<numeric> +B<New maintainer>, B<All codes are generated from standards>, B<Added +several code sets from standards>, B<Locale::Script changed>, B<Added +missing functions>, B<Dropped support for _alias_code> -=item CONVERSION ROUTINES +=item SEE ALSO -code2country( CODE, [ CODESET ] ), country2code( STRING, [ CODESET ] ), -country_code2code( CODE, CODESET, CODESET ) +=item AUTHOR -=item QUERY ROUTINES +=item COPYRIGHT -C<all_country_codes( [ CODESET ] )>, C<all_country_names( [ CODESET ] )> +=back -=item SEMI-PRIVATE ROUTINES +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Codes::Country, +Locale::Codes::Country - country codes for the Locale::Country module =over 4 -=item alias_code +=item SYNOPSIS + +=item AUTHOR -=item rename_country +=item COPYRIGHT =back -=item EXAMPLES +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Codes::Currency, +Locale::Codes::Currency - currency codes for the Locale::Currency module -=item DOMAIN NAMES +=over 4 -=item KNOWN BUGS AND LIMITATIONS +=item SYNOPSIS -=item SEE ALSO +=item AUTHOR -Locale::Language, Locale::Script, Locale::Currency, Locale::SubCountry, ISO -3166-1, http://www.iso.org/iso/en/prods-services/iso3166ma/index.html, -http://www.egt.ie/standards/iso3166/iso3166-1-en.html, -http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html +=item COPYRIGHT + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Codes::Language, +Locale::Codes::Language - language codes for the Locale::Language module + +=over 4 + +=item SYNOPSIS =item AUTHOR @@ -26212,33 +27160,74 @@ http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html =back -=head2 Locale::Currency - ISO three letter codes for currency -identification (ISO 4217) +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Codes::Script, +Locale::Codes::Script - script codes for the Locale::Script module =over 4 =item SYNOPSIS +=item AUTHOR + +=item COPYRIGHT + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Constants, Locale::Constants - +constants for Locale codes + +=over 4 + =item DESCRIPTION -XTS, XXX +=item KNOWN BUGS AND LIMITATIONS + +=item SEE ALSO -=item CONVERSION ROUTINES +=item AUTHOR -code2currency(), currency2code() +=item COPYRIGHT -=item QUERY ROUTINES +=back -C<all_currency_codes()>, C<all_currency_names()> +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Country, Locale::Country - +standard codes for country identification -=item EXAMPLES +=over 4 -=item KNOWN BUGS AND LIMITATIONS +=item SYNOPSIS + +=item DESCRIPTION + +=item SUPPORTED CODE SETS + +B<alpha-2>, B<alpha-3>, B<numeric>, B<fips-10>, B<dom> + +=item ROUTINES + +B<code2country ( CODE [,CODESET] )>, B<country2code ( NAME [,CODESET] )>, +B<country_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_country_codes ( +[CODESET] )>, B<all_country_names ( [CODESET] )>, +B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )>, +B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )>, +B<Locale::Country::delete_country ( CODE [,CODESET] )>, +B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )>, +B<Locale::Country::delete_country_alias ( NAME )>, +B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )>, +B<alias_code ( ALIAS, CODE [,CODESET] )> =item SEE ALSO -Locale::Country, Locale::Script, ISO 4217:1995, -http://www.bsi-global.com/iso4217currency +B<Locale::Codes>, B<Locale::Constants>, B<Locale::SubCountry>, +B<http://www.iso.org/iso/country_codes>, +B<http://www.iso.org/iso/list-en1-semic-3.txt>, +B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm>, +B<http://earth-info.nga.mil/gns/html/digraphs.htm>, +B<http://www.iana.org/domains/>, +B<https://www.cia.gov/library/publications/the-world-factbook/appendix/prin +t_appendix-d.html>, B<http://www.statoids.com/wab.html> =item AUTHOR @@ -26246,8 +27235,8 @@ http://www.bsi-global.com/iso4217currency =back -=head2 Locale::Language - ISO two letter codes for language identification -(ISO 639) +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Currency, Locale::Currency - +standard codes for currency identification =over 4 @@ -26255,22 +27244,66 @@ http://www.bsi-global.com/iso4217currency =item DESCRIPTION -=item CONVERSION ROUTINES +=item SUPPORTED CODE SETS -code2language(), language2code() +B<alpha>, B<num> -=item QUERY ROUTINES +=item ROUTINES -C<all_language_codes()>, C<all_language_names()> +B<code2currency ( CODE [,CODESET] )>, B<currency2code ( NAME [,CODESET] )>, +B<currency_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_currency_codes ( +[CODESET] )>, B<all_currency_names ( [CODESET] )>, +B<Locale::Currency::rename_currency ( CODE ,NEW_NAME [,CODESET] )>, +B<Locale::Currency::add_currency ( CODE ,NAME [,CODESET] )>, +B<Locale::Currency::delete_currency ( CODE [,CODESET] )>, +B<Locale::Currency::add_currency_alias ( NAME ,NEW_NAME )>, +B<Locale::Currency::delete_currency_alias ( NAME )>, +B<Locale::Currency::rename_currency_code ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Currency::add_currency_code_alias ( CODE ,NEW_CODE [,CODESET] +)>, B<Locale::Currency::delete_currency_code_alias ( CODE [,CODESET] )> -=item EXAMPLES +=item SEE ALSO -=item KNOWN BUGS AND LIMITATIONS +B<Locale::Codes>, B<Locale::Constants>, +B<http://www.iso.org/iso/support/currency_codes_list-1.htm> + +=item AUTHOR + +=item COPYRIGHT + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Language, Locale::Language - +standard codes for language identification + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SUPPORTED CODE SETS + +B<alpha-2>, B<alpha-3>, B<term> + +=item ROUTINES + +B<code2language ( CODE [,CODESET] )>, B<language2code ( NAME [,CODESET] )>, +B<language_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_language_codes ( +[CODESET] )>, B<all_language_names ( [CODESET] )>, +B<Locale::Language::rename_language ( CODE ,NEW_NAME [,CODESET] )>, +B<Locale::Language::add_language ( CODE ,NAME [,CODESET] )>, +B<Locale::Language::delete_language ( CODE [,CODESET] )>, +B<Locale::Language::add_language_alias ( NAME ,NEW_NAME )>, +B<Locale::Language::delete_language_alias ( NAME )>, +B<Locale::Language::rename_language_code ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Language::add_language_code_alias ( CODE ,NEW_CODE [,CODESET] +)>, B<Locale::Language::delete_language_code_alias ( CODE [,CODESET] )> =item SEE ALSO -Locale::Country, Locale::Script, Locale::Currency, ISO 639:1988 (E/F), -http://lcweb.loc.gov/standards/iso639-2/langhome.html +B<Locale::Codes>, B<Locale::Constants>, +B<http://www.loc.gov/standards/iso639-2/> =item AUTHOR @@ -26278,7 +27311,8 @@ http://lcweb.loc.gov/standards/iso639-2/langhome.html =back -=head2 Locale::Maketext - framework for localization +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Maketext, Locale::Maketext - +framework for localization =over 4 @@ -26317,6 +27351,8 @@ $language->language_tag(), $language->encoding() =item AUTO LEXICONS +=item READONLY LEXICONS + =item CONTROLLING LOOKUP FAILURE =item HOW TO USE MAKETEXT @@ -26329,8 +27365,45 @@ $language->language_tag(), $language->encoding() =back -=head2 Locale::Maketext::Simple - Simple interface to -Locale::Maketext::Lexicon +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Maketext::Cookbook, +Locale::Maketext::Cookbook - recipes for using Locale::Maketext + +=over 4 + +=item INTRODUCTION + +=item ONESIDED LEXICONS + +=item DECIMAL PLACES IN NUMBER FORMATTING + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Maketext::Guts, +Locale::Maketext::Guts - Deprecated module to load Locale::Maketext utf8 +code + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Maketext::GutsLoader, +Locale::Maketext::GutsLoader - Deprecated module to load Locale::Maketext +utf8 code + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Maketext::Simple, +Locale::Maketext::Simple - Simple interface to Locale::Maketext::Lexicon =over 4 @@ -26380,7 +27453,8 @@ Locale::Maketext::Lexicon =back -=head2 Locale::Maketext::TPJ13 -- article about software localization +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Maketext::TPJ13, +Locale::Maketext::TPJ13 -- article about software localization =over 4 @@ -26418,7 +27492,8 @@ Locale::Maketext::Lexicon =back -=head2 Locale::Script - ISO codes for script identification (ISO 15924) +=head2 C:\perl_tl\perl-5.14.2\lib::Locale::Script, Locale::Script - +standard codes for script identification =over 4 @@ -26426,31 +27501,27 @@ Locale::Maketext::Lexicon =item DESCRIPTION -B<alpha-2>, B<alpha-3>, B<numeric> - -=over 4 - -=item SPECIAL CODES - -=back - -=item CONVERSION ROUTINES +=item SUPPORTED CODE SETS -code2script( CODE, [ CODESET ] ), script2code( STRING, [ CODESET ] ), -script_code2code( CODE, CODESET, CODESET ) +B<alpha>, B<numeric> -=item QUERY ROUTINES +=item ROUTINES -C<all_script_codes ( [ CODESET ] )>, C<all_script_names ( [ CODESET ] )> - -=item EXAMPLES - -=item KNOWN BUGS AND LIMITATIONS +B<code2script ( CODE [,CODESET] )>, B<script2code ( NAME [,CODESET] )>, +B<script_code2code ( CODE ,CODESET ,CODESET2 )>, B<all_script_codes ( +[CODESET] )>, B<all_script_names ( [CODESET] )>, +B<Locale::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )>, +B<Locale::Script::add_script ( CODE ,NAME [,CODESET] )>, +B<Locale::Script::delete_script ( CODE [,CODESET] )>, +B<Locale::Script::add_script_alias ( NAME ,NEW_NAME )>, +B<Locale::Script::delete_script_alias ( NAME )>, +B<Locale::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )>, +B<Locale::Script::delete_script_code_alias ( CODE [,CODESET] )> =item SEE ALSO -Locale::Language, Locale::Currency, Locale::Country, ISO 15924, -http://www.evertype.com/standards/iso15924/ +B<Locale::Codes>, B<Locale::Constants>, B<http://www.unicode.org/iso15924/> =item AUTHOR @@ -26458,7 +27529,8 @@ http://www.evertype.com/standards/iso15924/ =back -=head2 Log::Message - A generic message storing mechanism; +=head2 C:\perl_tl\perl-5.14.2\lib::Log::Message, Log::Message - A generic +message storing mechanism; =over 4 @@ -26535,7 +27607,8 @@ tag, level, message, amount, chrono, remove =back -=head2 Log::Message::Config - Configuration options for Log::Message +=head2 C:\perl_tl\perl-5.14.2\lib::Log::Message::Config, +Log::Message::Config - Configuration options for Log::Message =over 4 @@ -26553,7 +27626,8 @@ tag, level, message, amount, chrono, remove =back -=head2 Log::Message::Handlers - Message handlers for Log::Message +=head2 C:\perl_tl\perl-5.14.2\lib::Log::Message::Handlers, +Log::Message::Handlers - Message handlers for Log::Message =over 4 @@ -26627,7 +27701,8 @@ tag, level, message, amount, chrono, remove =back -=head2 Log::Message::Item - Message objects for Log::Message +=head2 C:\perl_tl\perl-5.14.2\lib::Log::Message::Item, Log::Message::Item +- Message objects for Log::Message =over 4 @@ -26669,7 +27744,8 @@ tag, level, message, amount, chrono, remove =back -=head2 Log::Message::Simple - Simplified interface to Log::Message +=head2 C:\perl_tl\perl-5.14.2\lib::Log::Message::Simple, +Log::Message::Simple - Simplified interface to Log::Message =over 4 @@ -26727,7 +27803,8 @@ $ERROR_FH, $MSG_FH, $DEBUG_FH, $STACKTRACE_ON_ERROR =back -=head2 MIME::Base64 - Encoding and decoding of base64 strings +=head2 C:\perl_tl\perl-5.14.2\lib::MIME::Base64, MIME::Base64 - Encoding +and decoding of base64 strings =over 4 @@ -26735,12 +27812,10 @@ $ERROR_FH, $MSG_FH, $DEBUG_FH, $STACKTRACE_ON_ERROR =item DESCRIPTION -encode_base64($str), encode_base64($str, $eol);, decode_base64($str) - -=item DIAGNOSTICS - -Premature end of base64 data, Premature padding of base64 data, Wide -character in subroutine entry +encode_base64( $bytes ), encode_base64( $bytes, $eol );, decode_base64( +$str ), encode_base64url( $bytes ), decode_base64url( $str ), +encoded_base64_length( $bytes ), encoded_base64_length( $bytes, $eol ), +decoded_base64_length( $str ) =item EXAMPLES @@ -26750,8 +27825,8 @@ character in subroutine entry =back -=head2 MIME::QuotedPrint - Encoding and decoding of quoted-printable -strings +=head2 C:\perl_tl\perl-5.14.2\lib::MIME::QuotedPrint, MIME::QuotedPrint - +Encoding and decoding of quoted-printable strings =over 4 @@ -26759,8 +27834,8 @@ strings =item DESCRIPTION -encode_qp($str), encode_qp($str, $eol), encode_qp($str, $eol, $binmode), -decode_qp($str); +encode_qp( $str), encode_qp( $str, $eol), encode_qp( $str, $eol, $binmode +), decode_qp( $str ) =item COPYRIGHT @@ -26768,7 +27843,8 @@ decode_qp($str); =back -=head2 Math::BigFloat - Arbitrary size floating point math package +=head2 C:\perl_tl\perl-5.14.2\lib::Math::BigFloat, Math::BigFloat - +Arbitrary size floating point math package =over 4 @@ -26846,7 +27922,8 @@ accuracy() =back -=head2 Math::BigInt - Arbitrary size integer/float math package +=head2 C:\perl_tl\perl-5.14.2\lib::Math::BigInt, Math::BigInt - Arbitrary +size integer/float math package =over 4 @@ -26888,9 +27965,6 @@ Input, Output =item is_pos()/is_neg()/is_positive()/is_negative() - $x->is_pos(); # true if > 0 - $x->is_neg(); # true if < 0 - =item is_odd()/is_even()/is_int() =item bcmp() @@ -26989,6 +28063,8 @@ Input, Output =item as_int()/as_number() +=item bstr() + =item bsstr() =item as_hex() @@ -27046,8 +28122,6 @@ oct()/hex(), log(-inf), exp(), cos(), sin(), atan2() =item EXAMPLES - use Math::BigInt; - =item Autocreating constants =item PERFORMANCE @@ -27088,7 +28162,8 @@ bsqrt(), brsft() =back -=head2 Math::BigInt::Calc - Pure Perl module to support Math::BigInt +=head2 C:\perl_tl\perl-5.14.2\lib::Math::BigInt::Calc, Math::BigInt::Calc - +Pure Perl module to support Math::BigInt =over 4 @@ -27096,25 +28171,50 @@ bsqrt(), brsft() =item DESCRIPTION -=item STORAGE +=item THE Math::BigInt API -=item METHODS +=over 4 + +=item General Notes + +=item API version 1 + +I<api_version()>, I<_new(STR)>, I<_zero()>, I<_one()>, I<_two()>, +I<_ten()>, I<_from_bin(STR)>, I<_from_oct(STR)>, I<_from_hex(STR)>, +I<_add(OBJ1, OBJ2)>, I<_mul(OBJ1, OBJ2)>, I<_div(OBJ1, OBJ2)>, I<_sub(OBJ1, +OBJ2, FLAG)>, I<_sub(OBJ1, OBJ2)>, I<_dec(OBJ)>, I<_inc(OBJ)>, I<_mod(OBJ1, +OBJ2)>, I<_sqrt(OBJ)>, I<_root(OBJ, N)>, I<_fac(OBJ)>, I<_pow(OBJ1, OBJ2)>, +I<_modinv(OBJ1, OBJ2)>, I<_modpow(OBJ1, OBJ2, OBJ3)>, I<_rsft(OBJ, N, B)>, +I<_lsft(OBJ, N, B)>, I<_log_int(OBJ, B)>, I<_gcd(OBJ1, OBJ2)>, I<_and(OBJ1, +OBJ2)>, I<_or(OBJ1, OBJ2)>, I<_xor(OBJ1, OBJ2)>, I<_is_zero(OBJ)>, +I<_is_one(OBJ)>, I<_is_two(OBJ)>, I<_is_ten(OBJ)>, I<_is_even(OBJ)>, +I<_is_odd(OBJ)>, I<_acmp(OBJ1, OBJ2)>, I<_str(OBJ)>, I<_as_bin(OBJ)>, +I<_as_oct(OBJ)>, I<_as_hex(OBJ)>, I<_num(OBJ)>, I<_copy(OBJ)>, +I<_len(OBJ)>, I<_zeros(OBJ)>, I<_digit(OBJ, N)>, I<_check(OBJ)> + +=item API version 2 + +I<_1ex(N)>, I<_nok(OBJ1, OBJ2)>, I<_alen(OBJ)> + +=item API optional methods + +I<_signed_or(OBJ1, OBJ2, SIGN1, SIGN2)>, I<_signed_and(OBJ1, OBJ2, SIGN1, +SIGN2)>, I<_signed_xor(OBJ1, OBJ2, SIGN1, SIGN2)> + +=back =item WRAP YOUR OWN =item LICENSE -This program is free software; you may redistribute it and/or modify it -under -the same terms as Perl itself. - =item AUTHORS =item SEE ALSO =back -=head2 Math::BigInt::CalcEmu - Emulate low-level math with BigInt code +=head2 C:\perl_tl\perl-5.14.2\lib::Math::BigInt::CalcEmu, +Math::BigInt::CalcEmu - Emulate low-level math with BigInt code =over 4 @@ -27136,18 +28236,14 @@ the same terms as Perl itself. =item LICENSE -This program is free software; you may redistribute it and/or modify it -under -the same terms as Perl itself. - =item AUTHORS =item SEE ALSO =back -=head2 Math::BigInt::FastCalc - Math::BigInt::Calc with some XS for more -speed +=head2 C:\perl_tl\perl-5.14.2\lib::Math::BigInt::FastCalc, +Math::BigInt::FastCalc - Math::BigInt::Calc with some XS for more speed =over 4 @@ -27161,17 +28257,14 @@ speed =item LICENSE -This program is free software; you may redistribute it and/or modify it -under -the same terms as Perl itself. - =item AUTHORS =item SEE ALSO =back -=head2 Math::BigRat - Arbitrary big rational numbers +=head2 C:\perl_tl\perl-5.14.2\lib::Math::BigRat, Math::BigRat - Arbitrary +big rational numbers =over 4 @@ -27195,8 +28288,6 @@ the same terms as Perl itself. =item denominator() - $d = $x->denominator(); - =item parts() =item numify() @@ -27245,16 +28336,10 @@ the same terms as Perl itself. =item bfloor() - $x->bfloor(); - =item bsqrt() - $x->bsqrt(); - =item broot() - $x->broot($n); - =item badd()/bmul()/bsub()/bdiv()/bdec()/binc() =item copy() @@ -27291,8 +28376,8 @@ blog(), bmodinv() and bmodpow() (partial) =back -=head2 Math::Complex - complex numbers and associated mathematical -functions +=head2 C:\perl_tl\perl-5.14.2\lib::Math::Complex, Math::Complex - complex +numbers and associated mathematical functions =over 4 @@ -27338,7 +28423,8 @@ functions =back -=head2 Math::Trig - trigonometric functions +=head2 C:\perl_tl\perl-5.14.2\lib::Math::Trig, Math::Trig - trigonometric +functions =over 4 @@ -27414,7 +28500,8 @@ asin_real, acos_real =back -=head2 Memoize - Make functions faster by trading space for time +=head2 C:\perl_tl\perl-5.14.2\lib::Memoize, Memoize - Make functions faster +by trading space for time =over 4 @@ -27466,8 +28553,9 @@ C<MEMORY>, C<HASH>, C<TIE>, C<FAULT>, C<MERGE> =back -=head2 Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for -Storable use +=head2 C:\perl_tl\perl-5.14.2\lib::Memoize::AnyDBM_File, +Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for Storable +use =over 4 @@ -27475,8 +28563,8 @@ Storable use =back -=head2 Memoize::Expire - Plug-in module for automatic expiration of -memoized values +=head2 C:\perl_tl\perl-5.14.2\lib::Memoize::Expire, Memoize::Expire - +Plug-in module for automatic expiration of memoized values =over 4 @@ -27498,7 +28586,8 @@ memoized values =back -=head2 Memoize::ExpireFile - test for Memoize expiration semantics +=head2 C:\perl_tl\perl-5.14.2\lib::Memoize::ExpireFile, Memoize::ExpireFile +- test for Memoize expiration semantics =over 4 @@ -27506,7 +28595,8 @@ memoized values =back -=head2 Memoize::ExpireTest - test for Memoize expiration semantics +=head2 C:\perl_tl\perl-5.14.2\lib::Memoize::ExpireTest, Memoize::ExpireTest +- test for Memoize expiration semantics =over 4 @@ -27514,8 +28604,8 @@ memoized values =back -=head2 Memoize::NDBM_File - glue to provide EXISTS for NDBM_File for -Storable use +=head2 C:\perl_tl\perl-5.14.2\lib::Memoize::NDBM_File, Memoize::NDBM_File - +glue to provide EXISTS for NDBM_File for Storable use =over 4 @@ -27523,8 +28613,8 @@ Storable use =back -=head2 Memoize::SDBM_File - glue to provide EXISTS for SDBM_File for -Storable use +=head2 C:\perl_tl\perl-5.14.2\lib::Memoize::SDBM_File, Memoize::SDBM_File - +glue to provide EXISTS for SDBM_File for Storable use =over 4 @@ -27532,7 +28622,8 @@ Storable use =back -=head2 Memoize::Storable - store Memoized data in Storable database +=head2 C:\perl_tl\perl-5.14.2\lib::Memoize::Storable, Memoize::Storable - +store Memoized data in Storable database =over 4 @@ -27540,7 +28631,8 @@ Storable use =back -=head2 Module::Build - Build and install Perl modules +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build, Module::Build - Build and +install Perl modules =over 4 @@ -27557,10 +28649,11 @@ Cookbook (L<Module::Build::Cookbook>) =item ACTIONS build, clean, code, config_data, diff, dist, distcheck, distclean, distdir, -distmeta, distsign, disttest, docs, fakeinstall, help, html, install, -installdeps, manifest, manpages, pardist, ppd, ppmdist, prereq_data, -prereq_report, pure_install, realclean, retest, skipcheck, test, testall, -testcover, testdb, testpod, testpodcoverage, versioninstall +distinstall, distmeta, distsign, disttest, docs, fakeinstall, help, html, +install, installdeps, manifest, manifest_skip, manpages, pardist, ppd, +ppmdist, prereq_data, prereq_report, pure_install, realclean, retest, +skipcheck, test, testall, testcover, testdb, testpod, testpodcoverage, +versioninstall =item OPTIONS @@ -27597,7 +28690,8 @@ install_path, install_base, destdir, prefix =back -=head2 Module::Build::API - API Reference for Module Authors +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::API, Module::Build::API - +API Reference for Module Authors =over 4 @@ -27610,15 +28704,16 @@ install_path, install_base, destdir, prefix current(), new(), add_to_cleanup, auto_configure_requires, auto_features, autosplit, build_class, build_requires, create_packlist, c_source, conflicts, create_license, create_makefile_pl, create_readme, -dist_abstract, dist_author, dist_name, dist_version, dist_version_from, -dynamic_config, extra_compiler_flags, extra_linker_flags, get_options, -type, store, default, include_dirs, install_path, installdirs, license, -apache, apache_1_1, artistic, artistic_2, bsd, gpl, lgpl, mit, mozilla, -open_source, perl, restrictive, unrestricted, meta_add, meta_merge, -module_name, needs_compiler, PL_files, pm_files, pod_files, recommends, -recursive_test_files, requires, script_files, share_dir, sign, test_files, -use_tap_harness, tap_harness_args, xs_files, new_from_context(%args), -resume(), subclass(), add_property, C<default>, C<check>, property_error +dist_abstract, dist_author, dist_name, dist_suffix, dist_version, +dist_version_from, dynamic_config, extra_compiler_flags, +extra_linker_flags, get_options, type, store, default, include_dirs, +install_path, installdirs, license, apache, apache_1_1, artistic, +artistic_2, bsd, gpl, lgpl, mit, mozilla, open_source, perl, restrictive, +unrestricted, meta_add, meta_merge, module_name, needs_compiler, PL_files, +pm_files, pod_files, recommends, recursive_test_files, release_status, +requires, script_files, share_dir, sign, test_files, use_tap_harness, +tap_harness_args, xs_files, new_from_context(%args), resume(), subclass(), +add_property, C<default>, C<check>, property_error =item METHODS @@ -27649,6 +28744,22 @@ up_to_date($source_file, $derived_file), up_to_date(\@source_files, =item Autogenerated Accessors +PL_files(), allow_mb_mismatch(), auto_configure_requires(), autosplit(), +base_dir(), bindoc_dirs(), blib(), build_bat(), build_class(), +build_elements(), build_requires(), build_script(), bundle_inc(), +bundle_inc_preload(), c_source(), config_dir(), configure_requires(), +conflicts(), cpan_client(), create_license(), create_makefile_pl(), +create_packlist(), create_readme(), debug(), debugger(), destdir(), +dynamic_config(), get_options(), html_css(), include_dirs(), +install_base(), installdirs(), libdoc_dirs(), license(), magic_number(), +mb_version(), meta_add(), meta_merge(), metafile(), metafile2(), +module_name(), mymetafile(), mymetafile2(), needs_compiler(), orig_dir(), +perl(), pm_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 =item MODULE METADATA @@ -27663,7 +28774,8 @@ keywords, resources =back -=head2 Module::Build::Authoring - Authoring Module::Build modules +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Authoring, +Module::Build::Authoring - Authoring Module::Build modules =over 4 @@ -27701,7 +28813,8 @@ configure_requires, build_requires, requires, recommends, conflicts =back -=head2 Module::Build::Base - Default methods for Module::Build +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Base, Module::Build::Base +- Default methods for Module::Build =over 4 @@ -27717,8 +28830,8 @@ configure_requires, build_requires, requires, recommends, conflicts =back -=head2 Module::Build::Bundling - How to bundle Module::Build with a -distribution +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Bundling, +Module::Build::Bundling - How to bundle Module::Build with a distribution =over 4 @@ -27740,7 +28853,8 @@ distribution =back -=head2 Module::Build::Compat - Compatibility with ExtUtils::MakeMaker +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Compat, +Module::Build::Compat - Compatibility with ExtUtils::MakeMaker =over 4 @@ -27764,7 +28878,8 @@ makefile =back -=head2 Module::Build::ConfigData - Configuration for Module::Build +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::ConfigData, +Module::Build::ConfigData - Configuration for Module::Build =over 4 @@ -27782,7 +28897,8 @@ auto_feature_names(), write() =back -=head2 Module::Build::Cookbook - Examples of Module::Build Usage +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Cookbook, +Module::Build::Cookbook - Examples of Module::Build Usage =over 4 @@ -27852,29 +28968,19 @@ to the testing, do I generate a test file =back -=head2 Module::Build::ModuleInfo, ModuleInfo - Gather package and POD -information from a perl module file +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::ModuleInfo, +Module::Build::ModuleInfo - DEPRECATED =over 4 =item DESCRIPTION -new_from_file($filename, collect_pod => 1), new_from_module($module, -collect_pod => 1, inc => \@dirs), name(), version($package), filename(), -packages_inside(), pod_inside(), contains_pod(), pod($section), -find_module_by_name($module, \@dirs), find_module_dir_by_name($module, -\@dirs) - -=item AUTHOR - -=item COPYRIGHT - =item SEE ALSO =back -=head2 Module::Build::Notes - Create persistent distribution configuration -modules +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Notes, +Module::Build::Notes - Create persistent distribution configuration modules =over 4 @@ -27888,7 +28994,8 @@ modules =back -=head2 Module::Build::Notes, NOTES_NAME - Configuration for MODULE_NAME +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Notes, NOTES_NAME - +Configuration for MODULE_NAME =over 4 @@ -27906,7 +29013,8 @@ auto_feature_names(), write() =back -=head2 Module::Build::PPMMaker - Perl Package Manager file creation +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::PPMMaker, +Module::Build::PPMMaker - Perl Package Manager file creation =over 4 @@ -27922,7 +29030,8 @@ auto_feature_names(), write() =back -=head2 Module::Build::Platform::Amiga - Builder class for Amiga platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::Amiga, +Module::Build::Platform::Amiga - Builder class for Amiga platforms =over 4 @@ -27934,7 +29043,8 @@ auto_feature_names(), write() =back -=head2 Module::Build::Platform::Default - Stub class for unknown platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::Default, +Module::Build::Platform::Default - Stub class for unknown platforms =over 4 @@ -27946,7 +29056,8 @@ auto_feature_names(), write() =back -=head2 Module::Build::Platform::EBCDIC - Builder class for EBCDIC platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::EBCDIC, +Module::Build::Platform::EBCDIC - Builder class for EBCDIC platforms =over 4 @@ -27958,7 +29069,8 @@ auto_feature_names(), write() =back -=head2 Module::Build::Platform::MPEiX - Builder class for MPEiX platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::MPEiX, +Module::Build::Platform::MPEiX - Builder class for MPEiX platforms =over 4 @@ -27970,7 +29082,8 @@ auto_feature_names(), write() =back -=head2 Module::Build::Platform::MacOS - Builder class for MacOS platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::MacOS, +Module::Build::Platform::MacOS - Builder class for MacOS platforms =over 4 @@ -27990,7 +29103,8 @@ new(), make_executable(), dispatch(), ACTION_realclean() =back -=head2 Module::Build::Platform::RiscOS - Builder class for RiscOS platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::RiscOS, +Module::Build::Platform::RiscOS - Builder class for RiscOS platforms =over 4 @@ -28002,7 +29116,8 @@ new(), make_executable(), dispatch(), ACTION_realclean() =back -=head2 Module::Build::Platform::Unix - Builder class for Unix platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::Unix, +Module::Build::Platform::Unix - Builder class for Unix platforms =over 4 @@ -28014,7 +29129,8 @@ new(), make_executable(), dispatch(), ACTION_realclean() =back -=head2 Module::Build::Platform::VMS - Builder class for VMS platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::VMS, +Module::Build::Platform::VMS - Builder class for VMS platforms =over 4 @@ -28078,7 +29194,8 @@ ACTION_clean =back -=head2 Module::Build::Platform::VOS - Builder class for VOS platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::VOS, +Module::Build::Platform::VOS - Builder class for VOS platforms =over 4 @@ -28090,8 +29207,8 @@ ACTION_clean =back -=head2 Module::Build::Platform::Windows - Builder class for Windows -platforms +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::Windows, +Module::Build::Platform::Windows - Builder class for Windows platforms =over 4 @@ -28103,7 +29220,8 @@ platforms =back -=head2 Module::Build::Platform::aix - Builder class for AIX platform +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::aix, +Module::Build::Platform::aix - Builder class for AIX platform =over 4 @@ -28115,7 +29233,8 @@ platforms =back -=head2 Module::Build::Platform::cygwin - Builder class for Cygwin platform +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::cygwin, +Module::Build::Platform::cygwin - Builder class for Cygwin platform =over 4 @@ -28127,8 +29246,8 @@ platforms =back -=head2 Module::Build::Platform::darwin - Builder class for Mac OS X -platform +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::darwin, +Module::Build::Platform::darwin - Builder class for Mac OS X platform =over 4 @@ -28140,7 +29259,8 @@ platform =back -=head2 Module::Build::Platform::os2 - Builder class for OS/2 platform +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Platform::os2, +Module::Build::Platform::os2 - Builder class for OS/2 platform =over 4 @@ -28152,7 +29272,26 @@ platform =back -=head2 Module::CoreList - what modules shipped with versions of perl +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::Version, +Module::Build::Version - DEPRECATED + +=over 4 + +=item DESCRIPTION + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Build::YAML, Module::Build::YAML +- DEPRECATED + +=over 4 + +=item DESCRIPTION + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Module::CoreList, Module::CoreList - +what modules shipped with versions of perl =over 4 @@ -28185,7 +29324,8 @@ C<%Module::CoreList::upstream>, C<%Module::CoreList::bug_tracker> =back -=head2 Module::Load - runtime require of both modules and files +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Load, Module::Load - runtime +require of both modules and files =over 4 @@ -28207,8 +29347,9 @@ C<%Module::CoreList::upstream>, C<%Module::CoreList::bug_tracker> =back -=head2 Module::Load::Conditional - Looking up module information / loading -at runtime +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Load::Conditional, +Module::Load::Conditional - Looking up module information / loading at +runtime =over 4 @@ -28218,6 +29359,8 @@ at runtime =item Methods +=over 4 + =item $href = check_install( module => NAME [, version => VERSION, verbose => BOOL ] ); @@ -28225,6 +29368,8 @@ module, version, verbose, file, dir, version, uptodate =back +=back + =over 4 =item $bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] }, @@ -28270,7 +29415,8 @@ modules, verbose, nocache =back -=head2 Module::Loaded - mark modules as loaded or unloaded +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Loaded, Module::Loaded - mark +modules as loaded or unloaded =over 4 @@ -28310,8 +29456,28 @@ modules, verbose, nocache =back -=head2 Module::Pluggable - automatically give your module the ability to -have plugins +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Metadata, Module::Metadata - +Gather package and POD information from perl module files + +=over 4 + +=item DESCRIPTION + +new_from_file($filename, collect_pod => 1), new_from_module($module, +collect_pod => 1, inc => \@dirs), name(), version($package), filename(), +packages_inside(), pod_inside(), contains_pod(), pod($section), +find_module_by_name($module, \@dirs), find_module_dir_by_name($module, +\@dirs), package_versions_from_directory($dir, \@files?), log_info +(internal) + +=item AUTHOR + +=item COPYRIGHT + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Pluggable, Module::Pluggable - +automatically give your module the ability to have plugins =over 4 @@ -28373,8 +29539,9 @@ have plugins =back -=head2 Module::Pluggable::Object - automatically give your module the -ability to have plugins +=head2 C:\perl_tl\perl-5.14.2\lib::Module::Pluggable::Object, +Module::Pluggable::Object - automatically give your module the ability to +have plugins =over 4 @@ -28394,30 +29561,8 @@ ability to have plugins =back -=head2 NDBM_File - Tied access to ndbm files - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR> - -=item DIAGNOSTICS - -=over 4 - -=item C<ndbm store returned -1, errno 22, key "..." at ...> - -=back - -=item BUGS AND WARNINGS - -=back - -=head2 NEXT - Provide a pseudo-class NEXT (et al) that allows method -redispatch +=head2 C:\perl_tl\perl-5.14.2\lib::NEXT, NEXT.pm - Provide a pseudo-class +NEXT (et al) that allows method redispatch =over 4 @@ -28445,7 +29590,8 @@ redispatch =back -=head2 Net::Cmd - Network Command class (as used by FTP, SMTP etc) +=head2 C:\perl_tl\perl-5.14.2\lib::Net::Cmd, Net::Cmd - Network Command +class (as used by FTP, SMTP etc) =over 4 @@ -28472,7 +29618,8 @@ ungetline ( TEXT ), rawdatasend ( DATA ), read_until_dot (), tied_fh () =back -=head2 Net::Config - Local configuration data for libnet +=head2 C:\perl_tl\perl-5.14.2\lib::Net::Config, Net::Config - Local +configuration data for libnet =over 4 @@ -28492,8 +29639,8 @@ ftp_int_passive, local_netmask, test_hosts, test_exists =back -=head2 Net::Domain - Attempt to evaluate the current host's internet name -and domain +=head2 C:\perl_tl\perl-5.14.2\lib::Net::Domain, Net::Domain - Attempt to +evaluate the current host's internet name and domain =over 4 @@ -28509,7 +29656,7 @@ hostfqdn (), domainname (), hostname (), hostdomain () =back -=head2 Net::FTP - FTP Client class +=head2 C:\perl_tl\perl-5.14.2\lib::Net::FTP, Net::FTP - FTP Client class =over 4 @@ -28572,7 +29719,7 @@ http://www.csh.rit.edu/~adam/Progs/ =back -=head2 Net::NNTP - NNTP Client class +=head2 C:\perl_tl\perl-5.14.2\lib::Net::NNTP, Net::NNTP - NNTP Client class =over 4 @@ -28620,7 +29767,38 @@ MESSAGE-SPEC, PATTERN, Examples, C<[^]-]>, C<*bdc>, C<[0-9a-zA-Z]>, C<a??d> =back -=head2 Net::POP3 - Post Office Protocol 3 Client class (RFC1939) +=head2 C:\perl_tl\perl-5.14.2\lib::Net::Netrc, Net::Netrc - OO interface to +users netrc file + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item THE .netrc FILE + +machine name, default, login name, password string, account string, macdef +name + +=item CONSTRUCTOR + +lookup ( MACHINE [, LOGIN ]) + +=item METHODS + +login (), password (), account (), lpa () + +=item AUTHOR + +=item SEE ALSO + +=item COPYRIGHT + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Net::POP3, Net::POP3 - Post Office +Protocol 3 Client class (RFC1939) =over 4 @@ -28650,7 +29828,8 @@ auth ( USERNAME, PASSWORD ), user ( USER ), pass ( PASS ), login ( [ USER =back -=head2 Net::Ping - check a remote host for reachability +=head2 C:\perl_tl\perl-5.14.2\lib::Net::Ping, Net::Ping - check a remote +host for reachability =over 4 @@ -28683,7 +29862,8 @@ $p->port_number([$port_number]), pingecho($host [, $timeout]); =back -=head2 Net::SMTP - Simple Mail Transfer Protocol Client +=head2 C:\perl_tl\perl-5.14.2\lib::Net::SMTP, Net::SMTP - Simple Mail +Transfer Protocol Client =over 4 @@ -28717,7 +29897,8 @@ $subject ] ), quit () =back -=head2 Net::Time - time and daytime network client interface +=head2 C:\perl_tl\perl-5.14.2\lib::Net::Time, Net::Time - time and daytime +network client interface =over 4 @@ -28734,8 +29915,8 @@ PROTOCOL [, TIMEOUT]]]) =back -=head2 Net::hostent - by-name interface to Perl's built-in gethost*() -functions +=head2 C:\perl_tl\perl-5.14.2\lib::Net::hostent, Net::hostent - by-name +interface to Perl's built-in gethost*() functions =over 4 @@ -28751,7 +29932,8 @@ functions =back -=head2 Net::libnetFAQ, libnetFAQ - libnet Frequently Asked Questions +=head2 C:\perl_tl\perl-5.14.2\lib::Net::libnetFAQ, libnetFAQ - libnet +Frequently Asked Questions =over 4 @@ -28852,8 +30034,8 @@ hostname ? =back -=head2 Net::netent - by-name interface to Perl's built-in getnet*() -functions +=head2 C:\perl_tl\perl-5.14.2\lib::Net::netent, Net::netent - by-name +interface to Perl's built-in getnet*() functions =over 4 @@ -28869,8 +30051,8 @@ functions =back -=head2 Net::protoent - by-name interface to Perl's built-in getproto*() -functions +=head2 C:\perl_tl\perl-5.14.2\lib::Net::protoent, Net::protoent - by-name +interface to Perl's built-in getproto*() functions =over 4 @@ -28884,8 +30066,8 @@ functions =back -=head2 Net::servent - by-name interface to Perl's built-in getserv*() -functions +=head2 C:\perl_tl\perl-5.14.2\lib::Net::servent, Net::servent - by-name +interface to Perl's built-in getserv*() functions =over 4 @@ -28901,36 +30083,8 @@ functions =back -=head2 Netrc, Net::Netrc - OO interface to users netrc file - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item THE .netrc FILE - -machine name, default, login name, password string, account string, macdef -name - -=item CONSTRUCTOR - -lookup ( MACHINE [, LOGIN ]) - -=item METHODS - -login (), password (), account (), lpa () - -=item AUTHOR - -=item SEE ALSO - -=item COPYRIGHT - -=back - -=head2 O - Generic interface to Perl Compiler backends +=head2 C:\perl_tl\perl-5.14.2\lib::O, O - Generic interface to Perl +Compiler backends =over 4 @@ -28948,29 +30102,8 @@ login (), password (), account (), lpa () =back -=head2 ODBM_File - Tied access to odbm files - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR> - -=item DIAGNOSTICS - -=over 4 - -=item C<odbm store returned -1, errno 22, key "..." at ...> - -=back - -=item BUGS AND WARNINGS - -=back - -=head2 Object::Accessor - interface to create per object accessors +=head2 C:\perl_tl\perl-5.14.2\lib::Object::Accessor, Object::Accessor - +interface to create per object accessors =over 4 @@ -29105,7 +30238,8 @@ Allow handlers, Callbacks =back -=head2 Opcode - Disable named opcodes when compiling perl code +=head2 C:\perl_tl\perl-5.14.2\lib::Opcode, Opcode - Disable named opcodes +when compiling perl code =over 4 @@ -29150,20 +30284,8 @@ opdump (PAT) =back -=head2 Opcode::ops, ops - Perl pragma to restrict unsafe operations when -compiling - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item SEE ALSO - -=back - -=head2 POSIX - Perl interface to IEEE Std 1003.1 +=head2 C:\perl_tl\perl-5.14.2\lib::POSIX, POSIX - Perl interface to IEEE +Std 1003.1 =over 4 @@ -29297,7 +30419,8 @@ WTERMSIG, WIFSTOPPED, WSTOPSIG =back -=head2 Package::Constants - List all constants declared in a package +=head2 C:\perl_tl\perl-5.14.2\lib::Package::Constants, Package::Constants - +List all constants declared in a package =over 4 @@ -29337,7 +30460,8 @@ WTERMSIG, WIFSTOPPED, WSTOPSIG =back -=head2 Params::Check - A generic input parsing/checking mechanism. +=head2 C:\perl_tl\perl-5.14.2\lib::Params::Check, Params::Check - A generic +input parsing/checking mechanism. =over 4 @@ -29403,16 +30527,18 @@ string, regexp, subroutine, array ref =back -=item AUTHOR - =item Acknowledgements +=item BUG REPORTS + +=item AUTHOR + =item COPYRIGHT =back -=head2 Parse::CPAN::Meta - Parse META.yml and other similar CPAN metadata -files +=head2 C:\perl_tl\perl-5.14.2\lib::Parse::CPAN::Meta, Parse::CPAN::Meta - +Parse META.yml and META.json CPAN metadata files =over 4 @@ -29420,83 +30546,81 @@ files =item DESCRIPTION -=item FUNCTIONS +=item METHODS =over 4 -=item Load - -=item LoadFile - -=back +=item load_file -=item SUPPORT +=item load_yaml_string -=item AUTHOR +=item load_json_string -=item SEE ALSO +=item yaml_backend -=item COPYRIGHT +=item json_backend =back -=head2 PerlIO - On demand loader for PerlIO layers and root of PerlIO::* -name space +=item FUNCTIONS =over 4 -=item SYNOPSIS - -=item DESCRIPTION - -:unix, :stdio, :perlio, :crlf, :mmap, :utf8, :bytes, :raw, :pop, :win32 +=item Load -=over 4 +=item LoadFile -=item Custom Layers +=back -:encoding, :via +=item ENVIRONMENT -=item Alternatives to raw +=over 4 -=item Defaults and how to override them +=item PERL_JSON_BACKEND -=item Querying the layers of filehandles +=item PERL_YAML_BACKEND =back +=item SUPPORT + =item AUTHOR -=item SEE ALSO +=item COPYRIGHT =back -=head2 PerlIO-encoding, PerlIO::encoding - encoding layer +=head2 C:\perl_tl\perl-5.14.2\lib::Perl::OSType, Perl::OSType - Map Perl +operating system names to generic types =over 4 +=item VERSION + =item SYNOPSIS =item DESCRIPTION -=item SEE ALSO +=item USAGE -=back +=over 4 -=head2 PerlIO-scalar, PerlIO::scalar - in-memory IO, scalar IO +=item os_type() -=over 4 +=item is_os_type() -=item SYNOPSIS +=back -=item DESCRIPTION +=item SEE ALSO -=item IMPLEMENTATION NOTE +=item AUTHOR + +=item COPYRIGHT AND LICENSE =back -=head2 PerlIO-via, PerlIO::via - Helper class for PerlIO layers implemented -in perl +=head2 C:\perl_tl\perl-5.14.2\lib::PerlIO, PerlIO - On demand loader for +PerlIO layers and root of PerlIO::* name space =over 4 @@ -29504,28 +30628,30 @@ in perl =item DESCRIPTION -=item EXPECTED METHODS +:unix, :stdio, :perlio, :crlf, :mmap, :utf8, :bytes, :raw, :pop, :win32 -$class->PUSHED([$mode,[$fh]]), $obj->POPPED([$fh]), -$obj->UTF8($bellowFlag,[$fh]), $obj->OPEN($path,$mode,[$fh]), -$obj->BINMODE([$fh]), $obj->FDOPEN($fd,[$fh]), -$obj->SYSOPEN($path,$imode,$perm,[$fh]), $obj->FILENO($fh), -$obj->READ($buffer,$len,$fh), $obj->WRITE($buffer,$fh), $obj->FILL($fh), -$obj->CLOSE($fh), $obj->SEEK($posn,$whence,$fh), $obj->TELL($fh), -$obj->UNREAD($buffer,$fh), $obj->FLUSH($fh), $obj->SETLINEBUF($fh), -$obj->CLEARERR($fh), $obj->ERROR($fh), $obj->EOF($fh) +=over 4 -=item EXAMPLES +=item Custom Layers -=over 4 +:encoding, :via -=item Example - a Hexadecimal Handle +=item Alternatives to raw + +=item Defaults and how to override them + +=item Querying the layers of filehandles =back +=item AUTHOR + +=item SEE ALSO + =back -=head2 PerlIO::encoding - encoding layer +=head2 C:\perl_tl\perl-5.14.2\lib::PerlIO::encoding, PerlIO::encoding - +encoding layer =over 4 @@ -29537,7 +30663,8 @@ $obj->CLEARERR($fh), $obj->ERROR($fh), $obj->EOF($fh) =back -=head2 PerlIO::scalar - in-memory IO, scalar IO +=head2 C:\perl_tl\perl-5.14.2\lib::PerlIO::scalar, PerlIO::scalar - +in-memory IO, scalar IO =over 4 @@ -29549,7 +30676,8 @@ $obj->CLEARERR($fh), $obj->ERROR($fh), $obj->EOF($fh) =back -=head2 PerlIO::via - Helper class for PerlIO layers implemented in perl +=head2 C:\perl_tl\perl-5.14.2\lib::PerlIO::via, PerlIO::via - Helper class +for PerlIO layers implemented in perl =over 4 @@ -29578,7 +30706,8 @@ $obj->CLEARERR($fh), $obj->ERROR($fh), $obj->EOF($fh) =back -=head2 PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings +=head2 C:\perl_tl\perl-5.14.2\lib::PerlIO::via::QuotedPrint, +PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings =over 4 @@ -29596,7 +30725,8 @@ $obj->CLEARERR($fh), $obj->ERROR($fh), $obj->EOF($fh) =back -=head2 Pod::Checker, podchecker() - check pod documents for syntax errors +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Checker, Pod::Checker, podchecker() +- check pod documents for syntax errors =over 4 @@ -29678,7 +30808,8 @@ C<$checker-E<gt>hyperlink()> =back -=head2 Pod::Escapes -- for resolving Pod EE<lt>...E<gt> sequences +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Escapes, Pod::Escapes -- for +resolving Pod EE<lt>...E<gt> sequences =over 4 @@ -29702,7 +30833,8 @@ $Latin1Char_to_fallback{I<character>}, $Code2USASCII{I<integer>} =back -=head2 Pod::Find - find POD documents in directory trees +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Find, Pod::Find - find POD +documents in directory trees =over 4 @@ -29750,7 +30882,23 @@ C<-inc =E<gt> 1>, C<-dirs =E<gt> [ $dir1, $dir2, ... ]>, C<-verbose =E<gt> =back -=head2 Pod::Html - module to convert pod files to HTML +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Functions, Pod::Functions - Group +Perl's functions a la perlfunc.pod + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +%Kinds, %Type, %Flavor, %Type_Description, @Type_Order + +=item CHANGES + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Html, Pod::Html - module to convert +pod files to HTML =over 4 @@ -29784,8 +30932,8 @@ quiet, recurse, title, verbose =back -=head2 Pod::InputObjects - objects representing POD input paragraphs, -commands, etc. +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::InputObjects, Pod::InputObjects - +objects representing POD input paragraphs, commands, etc. =over 4 @@ -30014,7 +31162,8 @@ B<Pod::InteriorSequence>, package B<Pod::ParseTree> =back -=head2 Pod::LaTeX - Convert Pod data to formatted Latex +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::LaTeX, Pod::LaTeX - Convert Pod +data to formatted Latex =over 4 @@ -30136,7 +31285,8 @@ B<_split_delimited> =back -=head2 Pod::Man - Convert POD data to formatted *roff input +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Man, Pod::Man - Convert POD data to +formatted *roff input =over 4 @@ -30164,7 +31314,8 @@ roff font should be 1 or 2 chars, not "%s", Invalid quote specification =back -=head2 Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::ParseLink, Pod::ParseLink - Parse +an LE<lt>E<gt> formatting code in POD text =over 4 @@ -30180,7 +31331,8 @@ roff font should be 1 or 2 chars, not "%s", Invalid quote specification =back -=head2 Pod::ParseUtils - helpers for POD parsing and conversion +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::ParseUtils, Pod::ParseUtils - +helpers for POD parsing and conversion =over 4 @@ -30284,7 +31436,8 @@ $cacheitem-E<gt>idx() =back -=head2 Pod::Parser - base class for creating POD filters and translators +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Parser, Pod::Parser - base class +for creating POD filters and translators =over 4 @@ -30527,7 +31680,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc - Look up Perl documentation in Pod format. +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc, Pod::Perldoc - Look up +Perl documentation in Pod format. =over 4 @@ -30543,7 +31697,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::BaseTo - Base for Pod::Perldoc formatters +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::BaseTo, +Pod::Perldoc::BaseTo - Base for Pod::Perldoc formatters =over 4 @@ -30559,7 +31714,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::GetOptsOO - Customized option parser for Pod::Perldoc +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::GetOptsOO, +Pod::Perldoc::GetOptsOO - Customized option parser for Pod::Perldoc =over 4 @@ -30575,7 +31731,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::ToChecker - let Perldoc check Pod for errors +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::ToChecker, +Pod::Perldoc::ToChecker - let Perldoc check Pod for errors =over 4 @@ -30591,7 +31748,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::ToMan - let Perldoc render Pod as man pages +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::ToMan, Pod::Perldoc::ToMan +- let Perldoc render Pod as man pages =over 4 @@ -30609,7 +31767,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::ToNroff, +Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff =over 4 @@ -30627,7 +31786,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::ToPod - let Perldoc render Pod as ... Pod! +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::ToPod, Pod::Perldoc::ToPod +- let Perldoc render Pod as ... Pod! =over 4 @@ -30643,7 +31803,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::ToRtf - let Perldoc render Pod as RTF +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::ToRtf, Pod::Perldoc::ToRtf +- let Perldoc render Pod as RTF =over 4 @@ -30659,7 +31820,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::ToText - let Perldoc render Pod as plaintext +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::ToText, +Pod::Perldoc::ToText - let Perldoc render Pod as plaintext =over 4 @@ -30677,7 +31839,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::ToTk - let Perldoc use Tk::Pod to render Pod +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::ToTk, Pod::Perldoc::ToTk - +let Perldoc use Tk::Pod to render Pod =over 4 @@ -30691,7 +31854,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::Perldoc::ToXml - let Perldoc render Pod as XML +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Perldoc::ToXml, Pod::Perldoc::ToXml +- let Perldoc render Pod as XML =over 4 @@ -30707,7 +31871,8 @@ I<code-ref>|I<method-name> =back -=head2 Pod::PlainText - Convert POD data to formatted ASCII text +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::PlainText, Pod::PlainText - Convert +POD data to formatted ASCII text =over 4 @@ -30732,34 +31897,8 @@ Unknown sequence: %s, Unmatched =back =back -=head2 Pod::Plainer - Perl extension for converting Pod to old-style Pod. - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item METHODS - -escape_ltgt, simple_delimiters, textblock - -=item EXPORT - -=back - -=item AUTHOR - -=item SEE ALSO - -=item COPYRIGHT AND LICENSE - -=back - -=head2 Pod::Select, podselect() - extract selected sections of POD from -input +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Select, Pod::Select, podselect() - +extract selected sections of POD from input =over 4 @@ -30865,7 +32004,8 @@ B<-output>, B<-sections>, B<-ranges> =back -=head2 Pod::Simple - framework for parsing Pod +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple, Pod::Simple - framework for +parsing Pod =over 4 @@ -30907,7 +32047,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::Checker -- check the Pod syntax of a document +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::Checker, +Pod::Simple::Checker -- check the Pod syntax of a document =over 4 @@ -30928,7 +32069,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::Debug -- put Pod::Simple into trace/debug mode +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::Debug, Pod::Simple::Debug +-- put Pod::Simple into trace/debug mode =over 4 @@ -30953,7 +32095,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::DumpAsText -- dump Pod-parsing events as text +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::DumpAsText, +Pod::Simple::DumpAsText -- dump Pod-parsing events as text =over 4 @@ -30974,7 +32117,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::DumpAsXML -- turn Pod into XML +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::DumpAsXML, +Pod::Simple::DumpAsXML -- turn Pod into XML =over 4 @@ -30995,7 +32139,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::HTML - convert Pod to HTML +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::HTML, Pod::Simple::HTML - +convert Pod to HTML =over 4 @@ -31007,8 +32152,38 @@ David E. Wheeler C<dwheeler@cpan.org> =item CALLING FROM PERL +=over 4 + +=item Minimal code + +=item More detailed example + +=back + =item METHODS +=over 4 + +=item html_css + +=item html_javascript + +=item title_prefix + +=item title_postfix + +=item html_header_before_title + +=item html_h_level + +=item index + +=item html_header_after_title + +=item html_footer + +=back + =item SUBCLASSING =item SEE ALSO @@ -31026,8 +32201,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::HTMLBatch - convert several Pod files to several HTML -files +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::HTMLBatch, +Pod::Simple::HTMLBatch - convert several Pod files to several HTML files =over 4 @@ -31084,8 +32259,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::LinkSection -- represent "section" attributes of L -codes +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::LinkSection, +Pod::Simple::LinkSection -- represent "section" attributes of L codes =over 4 @@ -31106,7 +32281,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::Methody -- turn Pod::Simple events into method calls +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::Methody, +Pod::Simple::Methody -- turn Pod::Simple events into method calls =over 4 @@ -31129,7 +32305,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::PullParser -- a pull-parser interface to parsing Pod +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::PullParser, +Pod::Simple::PullParser -- a pull-parser interface to parsing Pod =over 4 @@ -31165,8 +32342,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::PullParserEndToken -- end-tokens from -Pod::Simple::PullParser +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::PullParserEndToken, +Pod::Simple::PullParserEndToken -- end-tokens from Pod::Simple::PullParser =over 4 @@ -31190,7 +32367,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::PullParserStartToken -- start-tokens from +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::PullParserStartToken, +Pod::Simple::PullParserStartToken -- start-tokens from Pod::Simple::PullParser =over 4 @@ -31219,7 +32397,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::PullParserTextToken -- text-tokens from +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::PullParserTextToken, +Pod::Simple::PullParserTextToken -- text-tokens from Pod::Simple::PullParser =over 4 @@ -31243,7 +32422,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::PullParserToken, +Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser =over 4 @@ -31267,7 +32447,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::RTF -- format Pod as RTF +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::RTF, Pod::Simple::RTF -- +format Pod as RTF =over 4 @@ -31300,7 +32481,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::Search - find POD documents in directory trees +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::Search, Pod::Simple::Search +- find POD documents in directory trees =over 4 @@ -31347,8 +32529,34 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::Subclassing -- write a formatter as a Pod::Simple -subclass +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::SimpleTree, +Pod::Simple::SimpleTree -- parse Pod into a simple parse tree + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=item Tree Contents + +=item SEE ALSO + +=item SUPPORT + +=item COPYRIGHT AND DISCLAIMERS + +=item AUTHOR + +Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>, +David E. Wheeler C<dwheeler@cpan.org> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::Subclassing, +Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass =over 4 @@ -31405,7 +32613,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::Text -- format Pod as plaintext +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::Text, Pod::Simple::Text -- +format Pod as plaintext =over 4 @@ -31426,7 +32635,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::TextContent -- get the text content of Pod +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::TextContent, +Pod::Simple::TextContent -- get the text content of Pod =over 4 @@ -31447,7 +32657,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::XHTML -- format Pod as validating XHTML +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::XHTML, Pod::Simple::XHTML +-- format Pod as validating XHTML =over 4 @@ -31455,6 +32666,12 @@ David E. Wheeler C<dwheeler@cpan.org> =item DESCRIPTION +=over 4 + +=item Minimal code + +=back + =back =over 4 @@ -31479,6 +32696,8 @@ David E. Wheeler C<dwheeler@cpan.org> =item html_doctype +=item html_charset + =item html_header_tags =item html_h_level @@ -31550,7 +32769,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::Simple::XMLOutStream -- turn Pod into XML +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Simple::XMLOutStream, +Pod::Simple::XMLOutStream -- turn Pod into XML =over 4 @@ -31577,33 +32797,8 @@ David E. Wheeler C<dwheeler@cpan.org> =back -=head2 Pod::SimpleTree, Pod::Simple::SimpleTree -- parse Pod into a simple -parse tree - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item METHODS - -=item Tree Contents - -=item SEE ALSO - -=item SUPPORT - -=item COPYRIGHT AND DISCLAIMERS - -=item AUTHOR - -Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org>, -David E. Wheeler C<dwheeler@cpan.org> - -=back - -=head2 Pod::Text - Convert POD data to formatted ASCII text +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Text, Pod::Text - Convert POD data +to formatted ASCII text =over 4 @@ -31632,7 +32827,8 @@ Bizarre space in item, Item called without tag, Can't open %s for reading: =back -=head2 Pod::Text::Color - Convert POD data to formatted color ASCII text +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Text::Color, Pod::Text::Color - +Convert POD data to formatted color ASCII text =over 4 @@ -31650,7 +32846,7 @@ Bizarre space in item, Item called without tag, Can't open %s for reading: =back -=head2 Pod::Text::Overstrike, =for stopwords +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Text::Overstrike, =for stopwords overstrike =over 4 @@ -31669,8 +32865,8 @@ overstrike =back -=head2 Pod::Text::Termcap - Convert POD data to ASCII text with format -escapes +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Text::Termcap, Pod::Text::Termcap - +Convert POD data to ASCII text with format escapes =over 4 @@ -31688,8 +32884,8 @@ escapes =back -=head2 Pod::Usage, pod2usage() - print a usage message from embedded pod -documentation +=head2 C:\perl_tl\perl-5.14.2\lib::Pod::Usage, Pod::Usage, pod2usage() - +print a usage message from embedded pod documentation =over 4 @@ -31720,7 +32916,8 @@ C<-input>, C<-pathlist>, C<-noperldoc> =back -=head2 SDBM_File - Tied access to sdbm files +=head2 C:\perl_tl\perl-5.14.2\lib::SDBM_File, SDBM_File - Tied access to +sdbm files =over 4 @@ -31742,7 +32939,8 @@ C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR> =back -=head2 Safe - Compile and execute code in restricted compartments +=head2 C:\perl_tl\perl-5.14.2\lib::Safe, Safe - Compile and execute code in +restricted compartments =over 4 @@ -31798,7 +32996,8 @@ Memory, CPU, Snooping, Signals, State Changes =back -=head2 Scalar::Util - A selection of general-utility scalar subroutines +=head2 C:\perl_tl\perl-5.14.2\lib::Scalar::Util, Scalar::Util - A selection +of general-utility scalar subroutines =over 4 @@ -31824,7 +33023,8 @@ XS version of Scalar::Util =back -=head2 Search::Dict, look - search for key in dictionary file +=head2 C:\perl_tl\perl-5.14.2\lib::Search::Dict, Search::Dict, look - +search for key in dictionary file =over 4 @@ -31834,7 +33034,8 @@ XS version of Scalar::Util =back -=head2 SelectSaver - save and restore selected file handle +=head2 C:\perl_tl\perl-5.14.2\lib::SelectSaver, SelectSaver - save and +restore selected file handle =over 4 @@ -31844,7 +33045,8 @@ XS version of Scalar::Util =back -=head2 SelfLoader - load functions only on demand +=head2 C:\perl_tl\perl-5.14.2\lib::SelfLoader, SelfLoader - load functions +only on demand =over 4 @@ -31878,7 +33080,8 @@ XS version of Scalar::Util B<_make_cmd> -=head2 Shell - run shell commands transparently within perl +=head2 C:\perl_tl\perl-5.14.2\lib::Shell, Shell - run shell commands +transparently within perl =over 4 @@ -31902,8 +33105,9 @@ B<_make_cmd> =back -=head2 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa, inet_pton, -inet_ntop - load the C socket.h defines and structure manipulators +=head2 C:\perl_tl\perl-5.14.2\lib::Socket, Socket, sockaddr_in, +sockaddr_un, inet_aton, inet_ntoa, inet_pton, inet_ntop - load the C +socket.h defines and structure manipulators =over 4 @@ -31912,15 +33116,23 @@ inet_ntop - load the C socket.h defines and structure manipulators =item DESCRIPTION inet_aton HOSTNAME, inet_ntoa IP_ADDRESS, INADDR_ANY, INADDR_BROADCAST, -INADDR_LOOPBACK, INADDR_NONE, sockaddr_family SOCKADDR, sockaddr_in PORT, -ADDRESS, sockaddr_in SOCKADDR_IN, pack_sockaddr_in PORT, IP_ADDRESS, -unpack_sockaddr_in SOCKADDR_IN, sockaddr_un PATHNAME, sockaddr_un -SOCKADDR_UN, pack_sockaddr_un PATH, unpack_sockaddr_un SOCKADDR_UN, -inet_pton ADDRESS_FAMILY, HOSTNAME, inet_ntop ADDRESS_FAMILY, IP_ADDRESS +INADDR_LOOPBACK, INADDR_NONE, IN6ADDR_ANY, IN6ADDR_LOOPBACK, +sockaddr_family SOCKADDR, sockaddr_in PORT, ADDRESS, sockaddr_in +SOCKADDR_IN, pack_sockaddr_in PORT, IP_ADDRESS, unpack_sockaddr_in +SOCKADDR_IN, sockaddr_in6 PORT, IP6_ADDRESS, [ SCOPE_ID, [ FLOWINFO ] ], +sockaddr_in6 SOCKADDR_IN6, pack_sockaddr_in6 PORT, IP6_ADDRESS, [ SCOPE_ID, +[ FLOWINFO ] ], unpack_sockaddr_in6 SOCKADDR_IN6, sockaddr_un PATHNAME, +sockaddr_un SOCKADDR_UN, pack_sockaddr_un PATH, unpack_sockaddr_un +SOCKADDR_UN, inet_pton ADDRESS_FAMILY, HOSTNAME, inet_ntop ADDRESS_FAMILY, +IP_ADDRESS, getaddrinfo HOST, SERVICE, [ HINTS ], flags => INT, family => +INT, socktype => INT, protocol => INT, family => INT, socktype => INT, +protocol => INT, addr => STRING, canonname => STRING, getnameinfo ADDR, +FLAGS =back -=head2 Storable - persistence for Perl data structures +=head2 C:\perl_tl\perl-5.14.2\lib::Storable, Storable - persistence for +Perl data structures =over 4 @@ -31991,66 +33203,21 @@ $buffer ), $info = Storable::read_magic( $buffer, $must_be_file ) =back -=head2 Switch - A switch statement for Perl +=head2 C:\perl_tl\perl-5.14.2\lib::Symbol, Symbol - manipulate Perl symbols +and their names =over 4 =item SYNOPSIS -=item BACKGROUND - =item DESCRIPTION -=over 4 - -=item Allowing fall-through - -=item Automating fall-through - -=item Alternative syntax - -=item Higher-order Operations - -=back - -=item DEPENDENCIES - -=item AUTHOR - =item BUGS -=item LIMITATIONS - -=item COPYRIGHT - =back -=head2 Symbol - manipulate Perl symbols and their names - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item BUGS - -=back - -=head2 Sys-Hostname, Sys::Hostname - Try every conceivable way to get -hostname - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item AUTHOR - -=back - -=head2 Sys::Hostname - Try every conceivable way to get hostname +=head2 C:\perl_tl\perl-5.14.2\lib::Sys::Hostname, Sys::Hostname - Try every +conceivable way to get hostname =over 4 @@ -32062,8 +33229,8 @@ hostname =back -=head2 TAP::Base - Base class that provides common functionality to -L<TAP::Parser> +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Base, TAP::Base - Base class that +provides common functionality to L<TAP::Parser> and L<TAP::Harness> =over 4 @@ -32088,8 +33255,8 @@ and L<TAP::Harness> =back -=head2 TAP::Formatter::Base, TAP::Formatter::Console - Harness output -delegate for default console output +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Formatter::Base, +TAP::Formatter::Base - Base class for harness output delegates =over 4 @@ -32121,7 +33288,8 @@ C<jobs>, C<show_count> =back -=head2 TAP::Formatter::Color - Run Perl test scripts with color +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Formatter::Color, +TAP::Formatter::Color - Run Perl test scripts with color =over 4 @@ -32145,8 +33313,9 @@ C<jobs>, C<show_count> =back -=head2 TAP::Formatter::Console - Harness output delegate for default -console output +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Formatter::Console, +TAP::Formatter::Console - Harness output delegate for default console +output =over 4 @@ -32168,8 +33337,10 @@ console output =back -=head2 TAP::Formatter::Console::ParallelSession - Harness output delegate -for parallel console output +=head2 +C:\perl_tl\perl-5.14.2\lib::TAP::Formatter::Console::ParallelSession, +TAP::Formatter::Console::ParallelSession - Harness output delegate for +parallel console output =over 4 @@ -32197,8 +33368,9 @@ for parallel console output =back -=head2 TAP::Formatter::Console::Session - Harness output delegate for -default console output +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Formatter::Console::Session, +TAP::Formatter::Console::Session - Harness output delegate for default +console output =over 4 @@ -32224,7 +33396,8 @@ default console output =back -=head2 TAP::Formatter::File - Harness output delegate for file output +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Formatter::File, +TAP::Formatter::File - Harness output delegate for file output =over 4 @@ -32246,8 +33419,8 @@ default console output =back -=head2 TAP::Formatter::File::Session - Harness output delegate for file -output +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Formatter::File::Session, +TAP::Formatter::File::Session - Harness output delegate for file output =over 4 @@ -32279,8 +33452,8 @@ output =back -=head2 TAP::Formatter::Session - Abstract base class for harness output -delegate +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Formatter::Session, +TAP::Formatter::Session - Abstract base class for harness output delegate =over 4 @@ -32302,7 +33475,8 @@ C<formatter>, C<parser>, C<name>, C<show_count> =back -=head2 TAP::Harness - Run test scripts with statistics +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Harness, TAP::Harness - Run test +scripts with statistics =over 4 @@ -32328,9 +33502,10 @@ C<formatter>, C<parser>, C<name>, C<show_count> C<verbosity>, C<timer>, C<failures>, C<comments>, C<show_count>, C<normalize>, 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<rules>, C<stdout> +C<merge>, C<sources>, C<aggregator_class>, C<version>, C<formatter_class>, +C<multiplexer_class>, C<parser_class>, C<scheduler_class>, C<formatter>, +C<errors>, C<directives>, C<ignore_exit>, C<jobs>, C<rules>, C<stdout>, +C<trap> =back @@ -32342,18 +33517,37 @@ C<directives>, C<ignore_exit>, C<jobs>, C<rules>, C<stdout> =back -the file name of a test script to run, a reference to a [ file name, -display name ] array +the source name of a test to run, a reference to a [ source name, display +name ] array + +=over 4 + +=item CONFIGURING =over 4 +=item Plugins + +=item C<Module::Build> + +=item C<ExtUtils::MakeMaker> + +=item C<prove> + +=back + +=item WRITING PLUGINS + +Customize how TAP gets into the parser, Customize how TAP results are +output from the parser + =item SUBCLASSING =over 4 =item Methods -C<start>, C<tests> +L</new>, L</runtests>, L</summary> =back @@ -32367,8 +33561,8 @@ C<start>, C<tests> =back -=head2 TAP::Object - Base class that provides common functionality to all -C<TAP::*> modules +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Object, TAP::Object - Base class +that provides common functionality to all C<TAP::*> modules =over 4 @@ -32398,7 +33592,8 @@ C<TAP::*> modules =back -=head2 TAParser, TAP::Parser - Parse L<TAP|Test::Harness::TAP> output +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser, TAP::Parser - Parse +L<TAP|Test::Harness::TAP> output =over 4 @@ -32418,9 +33613,9 @@ C<TAP::*> modules =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> +C<source>, C<tap>, C<exec>, C<sources>, C<callback>, C<switches>, +C<test_args>, C<spool>, C<merge>, C<grammar_class>, +C<result_factory_class>, C<iterator_factory_class> =back @@ -32495,7 +33690,7 @@ C<ELSE>, C<ALL>, C<EOF> =item TAP GRAMMAR -=item BACKWARDS COMPATABILITY +=item BACKWARDS COMPATIBILITY =over 4 @@ -32515,12 +33710,12 @@ option 1, option 2 =back -=item ACKNOWLEDGEMENTS +=item ACKNOWLEDGMENTS 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 +Kraai, David Wheeler, Alex Vandiver, Cosimo Streppone, Ville Skyttä =item AUTHORS @@ -32530,8 +33725,8 @@ Kraai, David Wheeler, Alex Vandiver =back -=head2 TAParser::Aggregator, TAP::Parser::Aggregator - Aggregate -TAP::Parser results +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Aggregator, +TAP::Parser::Aggregator - Aggregate TAP::Parser results =over 4 @@ -32578,8 +33773,8 @@ Failed tests, Parse errors, Bad exit or wait status =back -=head2 TAParser::Grammar, TAP::Parser::Grammar - A grammar for the Test -Anything Protocol. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Grammar, +TAP::Parser::Grammar - A grammar for the Test Anything Protocol. =over 4 @@ -32619,8 +33814,8 @@ Anything Protocol. =back -=head2 TAParser::Iterator, TAP::Parser::Iterator - Internal base class for -TAP::Parser Iterators +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Iterator, +TAP::Parser::Iterator - Base class for TAP source iterators =over 4 @@ -32660,8 +33855,8 @@ TAP::Parser Iterators =back -=head2 TAParser::Iterator::Array, TAP::Parser::Iterator::Array - Internal -TAP::Parser array Iterator +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Iterator::Array, +TAP::Parser::Iterator::Array - Iterator for array-based TAP sources =over 4 @@ -32695,8 +33890,8 @@ TAP::Parser array Iterator =back -=head2 TAParser::Iterator::Process, TAP::Parser::Iterator::Process - -Internal TAP::Parser Iterator +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Iterator::Process, +TAP::Parser::Iterator::Process - Iterator for process-based TAP sources =over 4 @@ -32730,8 +33925,8 @@ Internal TAP::Parser Iterator =back -=head2 TAParser::Iterator::Stream, TAP::Parser::Iterator::Stream - Internal -TAP::Parser Iterator +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Iterator::Stream, +TAP::Parser::Iterator::Stream - Iterator for filehandle-based TAP sources =over 4 @@ -32769,8 +33964,9 @@ TAP::Parser Iterator =back -=head2 TAParser::IteratorFactory, TAP::Parser::IteratorFactory - Internal -TAP::Parser Iterator +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::IteratorFactory, +TAP::Parser::IteratorFactory - Figures out which SourceHandler objects to +use for a given Source =over 4 @@ -32796,6 +33992,12 @@ TAP::Parser Iterator =over 4 +=item Instance Methods + +=back + +=over 4 + =item SUBCLASSING =over 4 @@ -32804,14 +34006,16 @@ TAP::Parser Iterator =back +=item AUTHORS + =item ATTRIBUTION =item SEE ALSO =back -=head2 TAParser::Multiplexer, TAP::Parser::Multiplexer - Multiplex multiple -TAP::Parsers +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Multiplexer, +TAP::Parser::Multiplexer - Multiplex multiple TAP::Parsers =over 4 @@ -32847,8 +34051,8 @@ TAP::Parsers =back -=head2 TAParser::Result, TAP::Parser::Result - Base class for TAP::Parser -output objects +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result, TAP::Parser::Result +- Base class for TAP::Parser output objects =over 4 @@ -32893,8 +34097,8 @@ C<is_version>, C<is_unknown>, C<is_yaml> =back -=head2 TAParser::Result::Bailout, TAP::Parser::Result::Bailout - Bailout -result token. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result::Bailout, +TAP::Parser::Result::Bailout - Bailout result token. =over 4 @@ -32918,8 +34122,8 @@ C<as_string> =back -=head2 TAParser::Result::Comment, TAP::Parser::Result::Comment - Comment -result token. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result::Comment, +TAP::Parser::Result::Comment - Comment result token. =over 4 @@ -32943,8 +34147,8 @@ C<as_string> =back -=head2 TAParser::Result::Plan, TAP::Parser::Result::Plan - Plan result -token. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result::Plan, +TAP::Parser::Result::Plan - Plan result token. =over 4 @@ -32968,8 +34172,8 @@ C<as_string>, C<raw> =back -=head2 TAParser::Result::Pragma, TAP::Parser::Result::Pragma - TAP pragma -token. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result::Pragma, +TAP::Parser::Result::Pragma - TAP pragma token. =over 4 @@ -32993,8 +34197,8 @@ C<as_string>, C<raw> =back -=head2 TAParser::Result::Test, TAP::Parser::Result::Test - Test result -token. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result::Test, +TAP::Parser::Result::Test - Test result token. =over 4 @@ -33016,8 +34220,8 @@ token. =back -=head2 TAParser::Result::Unknown, TAP::Parser::Result::Unknown - Unknown -result token. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result::Unknown, +TAP::Parser::Result::Unknown - Unknown result token. =over 4 @@ -33035,8 +34239,8 @@ C<as_string>, C<raw> =back -=head2 TAParser::Result::Version, TAP::Parser::Result::Version - TAP syntax -version token. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result::Version, +TAP::Parser::Result::Version - TAP syntax version token. =over 4 @@ -33060,8 +34264,8 @@ C<as_string>, C<raw> =back -=head2 TAParser::Result::YAML, TAP::Parser::Result::YAML - YAML result -token. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Result::YAML, +TAP::Parser::Result::YAML - YAML result token. =over 4 @@ -33085,8 +34289,9 @@ C<as_string>, C<raw> =back -=head2 TAParser::ResultFactory, TAP::Parser::ResultFactory - Factory for -creating TAP::Parser output objects +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::ResultFactory, +TAP::Parser::ResultFactory - Factory for creating TAP::Parser output +objects =over 4 @@ -33120,8 +34325,8 @@ creating TAP::Parser output objects =back -=head2 TAParser::Scheduler, TAP::Parser::Scheduler - Schedule tests during -parallel testing +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Scheduler, +TAP::Parser::Scheduler - Schedule tests during parallel testing =over 4 @@ -33145,8 +34350,8 @@ parallel testing =back -=head2 TAParser::Scheduler::Job, TAP::Parser::Scheduler::Job - A single -testing job. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Scheduler::Job, +TAP::Parser::Scheduler::Job - A single testing job. =over 4 @@ -33170,8 +34375,8 @@ testing job. =back -=head2 TAParser::Scheduler::Spinner, TAP::Parser::Scheduler::Spinner - A -no-op job. +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Scheduler::Spinner, +TAP::Parser::Scheduler::Spinner - A no-op job. =over 4 @@ -33195,8 +34400,8 @@ no-op job. =back -=head2 TAParser::Source, TAP::Parser::Source - Stream output from some -source +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Source, TAP::Parser::Source +- a TAP source & meta data about it =over 4 @@ -33228,6 +34433,39 @@ source =over 4 +=item AUTHORS + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::SourceHandler, +TAP::Parser::SourceHandler - Base class for different TAP source handlers + +=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 @@ -33236,12 +34474,15 @@ source =back +=item AUTHORS + =item SEE ALSO =back -=head2 TAParser::Source::Perl, TAP::Parser::Source::Perl - Stream Perl -output +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::SourceHandler::Executable, +TAP::Parser::SourceHandler::Executable - Stream output from an executable +TAP source =over 4 @@ -33261,7 +34502,113 @@ output =item Class Methods -=item Instance Methods +=back + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::SourceHandler::File, +TAP::Parser::SourceHandler::File - Stream TAP from a text file. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item CONFIGURATION + +=item SUBCLASSING + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::SourceHandler::Handle, +TAP::Parser::SourceHandler::Handle - Stream TAP from an IO::Handle or a +GLOB. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item SUBCLASSING + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::SourceHandler::Perl, +TAP::Parser::SourceHandler::Perl - Stream TAP from a Perl executable + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods =back @@ -33281,7 +34628,42 @@ output =back -=head2 TAParser::Utils, TAP::Parser::Utils - Internal TAP::Parser utilities +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::SourceHandler::RawTAP, +TAP::Parser::SourceHandler::RawTAP - Stream output from raw TAP in a +scalar/array ref. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item SUBCLASSING + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::Utils, TAP::Parser::Utils - +Internal TAP::Parser utilities =over 4 @@ -33303,8 +34685,8 @@ output =back -=head2 TAParser::YAMLish::Reader, TAP::Parser::YAMLish::Reader - Read -YAMLish data from iterator +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::YAMLish::Reader, +TAP::Parser::YAMLish::Reader - Read YAMLish data from iterator =over 4 @@ -33332,8 +34714,8 @@ YAMLish data from iterator =back -=head2 TAParser::YAMLish::Writer, TAP::Parser::YAMLish::Writer - Write -YAMLish data +=head2 C:\perl_tl\perl-5.14.2\lib::TAP::Parser::YAMLish::Writer, +TAP::Parser::YAMLish::Writer - Write YAMLish data =over 4 @@ -33364,7 +34746,8 @@ reference to an array into which YAML will be pushed, a code reference =back -=head2 Term::ANSIColor - Color screen output using ANSI escape sequences +=head2 C:\perl_tl\perl-5.14.2\lib::Term::ANSIColor, Term::ANSIColor - Color +screen output using ANSI escape sequences =over 4 @@ -33374,8 +34757,14 @@ reference to an array into which YAML will be pushed, a code reference =over 4 +=item Supported Colors + =item Function Interface +color(ATTR[, ATTR ...]), colored(STRING, ATTRIBUTES), colored(ATTR-REF, +STRING[, STRING...]), uncolor(ESCAPE), colorstrip(STRING[, STRING ...]), +colorvalid(ATTR[, ATTR ...]) + =item Constant Interface =item The Color Stack @@ -33404,7 +34793,8 @@ ANSI_COLORS_DISABLED =back -=head2 Term::Cap - Perl termcap interface +=head2 C:\perl_tl\perl-5.14.2\lib::Term::Cap, Term::Cap - Perl termcap +interface =over 4 @@ -33442,7 +34832,8 @@ B<Trequire> =back -=head2 Term::Complete - Perl word completion module +=head2 C:\perl_tl\perl-5.14.2\lib::Term::Complete, Term::Complete - Perl +word completion module =over 4 @@ -33460,7 +34851,8 @@ E<lt>tabE<gt>, ^D, ^U, E<lt>delE<gt>, E<lt>bsE<gt> =back -=head2 Term::ReadLine - Perl interface to various C<readline> packages. +=head2 C:\perl_tl\perl-5.14.2\lib::Term::ReadLine, Term::ReadLine - Perl +interface to various C<readline> packages. If no real package is found, substitutes stubs instead of basic functions. =over 4 @@ -33482,11 +34874,10 @@ C<tkRunning>, C<ornaments>, C<newTTY> =item ENVIRONMENT -=item CAVEATS - =back -=head2 Term::UI - Term::ReadLine UI made easy +=head2 C:\perl_tl\perl-5.14.2\lib::Term::UI, Term::UI - Term::ReadLine UI +made easy =over 4 @@ -33571,7 +34962,7 @@ record", allow => $ref] ); =back -=head2 Term::UI::History +=head2 C:\perl_tl\perl-5.14.2\lib::Term::UI::History, Term::UI::History =over 4 @@ -33603,7 +34994,8 @@ $HISTORY_FH =back -=head2 Test - provides a simple framework for writing test scripts +=head2 C:\perl_tl\perl-5.14.2\lib::Test, Test - provides a simple framework +for writing test scripts =over 4 @@ -33650,7 +35042,8 @@ NORMAL TESTS, SKIPPED TESTS, TODO TESTS =back -=head2 Test::Builder - Backend for building test libraries +=head2 C:\perl_tl\perl-5.14.2\lib::Test::Builder, Test::Builder - Backend +for building test libraries =over 4 @@ -33674,6 +35067,9 @@ B<child> B<subtest> +B<_plan_handled>, Explicitly setting the number of tests, Setting +'no_plan', Set 'skip_all' + B<finalize> B<parent> @@ -33828,7 +35224,8 @@ B<_my_exit> =back -=head2 Test::Builder::Module - Base class for test modules +=head2 C:\perl_tl\perl-5.14.2\lib::Test::Builder::Module, +Test::Builder::Module - Base class for test modules =over 4 @@ -33850,7 +35247,8 @@ B<_my_exit> =back -=head2 Test::Builder::Tester - test testsuites that have been built with +=head2 C:\perl_tl\perl-5.14.2\lib::Test::Builder::Tester, +Test::Builder::Tester - test testsuites that have been built with Test::Builder =over 4 @@ -33891,8 +35289,8 @@ color =back -=head2 Test::Builder::Tester::Color - turn on colour in -Test::Builder::Tester +=head2 C:\perl_tl\perl-5.14.2\lib::Test::Builder::Tester::Color, +Test::Builder::Tester::Color - turn on colour in Test::Builder::Tester =over 4 @@ -33912,7 +35310,8 @@ Test::Builder::Tester =back -=head2 Test::Harness - Run Perl standard test scripts with statistics +=head2 C:\perl_tl\perl-5.14.2\lib::Test::Harness, Test::Harness - Run Perl +standard test scripts with statistics =over 4 @@ -33953,7 +35352,7 @@ 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 >> +c >>, C<HARNESS_SUBCLASS> =item Taint Mode @@ -33967,7 +35366,8 @@ f >> =back -=head2 Test::More - yet another framework for writing test scripts +=head2 C:\perl_tl\perl-5.14.2\lib::Test::More, Test::More - yet another +framework for writing test scripts =over 4 @@ -34104,7 +35504,8 @@ objects, Threads =back -=head2 Test::Simple - Basic utilities for writing tests. +=head2 C:\perl_tl\perl-5.14.2\lib::Test::Simple, Test::Simple - Basic +utilities for writing tests. =over 4 @@ -34136,7 +35537,8 @@ L<Test::More> =back -=head2 Test::Tutorial - A tutorial about writing really basic tests +=head2 C:\perl_tl\perl-5.14.2\lib::Test::Tutorial, Test::Tutorial - A +tutorial about writing really basic tests =over 4 @@ -34174,7 +35576,8 @@ L<Test::More> =back -=head2 Text::Abbrev, abbrev - create an abbreviation table from a list +=head2 C:\perl_tl\perl-5.14.2\lib::Text::Abbrev, abbrev - create an +abbreviation table from a list =over 4 @@ -34186,7 +35589,8 @@ L<Test::More> =back -=head2 Text::Balanced - Extract delimited text sequences from strings. +=head2 C:\perl_tl\perl-5.14.2\lib::Text::Balanced, Text::Balanced - Extract +delimited text sequences from strings. =over 4 @@ -34261,8 +35665,8 @@ tag> =back -=head2 Text::ParseWords - parse text into an array of tokens or array of -arrays +=head2 C:\perl_tl\perl-5.14.2\lib::Text::ParseWords, Text::ParseWords - +parse text into an array of tokens or array of arrays =over 4 @@ -34276,7 +35680,8 @@ arrays =back -=head2 Text::Soundex - Implementation of the soundex algorithm. +=head2 C:\perl_tl\perl-5.14.2\lib::Text::Soundex, Text::Soundex - +Implementation of the soundex algorithm. =over 4 @@ -34294,8 +35699,8 @@ arrays =back -=head2 Text::Tabs -- expand and unexpand tabs per the unix expand(1) and -unexpand(1) +=head2 C:\perl_tl\perl-5.14.2\lib::Text::Tabs, Text::Tabs -- expand and +unexpand tabs per the unix expand(1) and unexpand(1) =over 4 @@ -34309,7 +35714,8 @@ unexpand(1) =back -=head2 Text::Wrap - line wrapping to form simple paragraphs +=head2 C:\perl_tl\perl-5.14.2\lib::Text::Wrap, Text::Wrap - line wrapping +to form simple paragraphs =over 4 @@ -34327,7 +35733,8 @@ unexpand(1) =back -=head2 Thread - Manipulate threads in Perl (for old code only) +=head2 C:\perl_tl\perl-5.14.2\lib::Thread, Thread - Manipulate threads in +Perl (for old code only) =over 4 @@ -34357,7 +35764,8 @@ lock(\&sub), eval, flags =back -=head2 Thread::Queue - Thread-safe queues +=head2 C:\perl_tl\perl-5.14.2\lib::Thread::Queue, Thread::Queue - +Thread-safe queues =over 4 @@ -34396,7 +35804,8 @@ above =back -=head2 Thread::Semaphore - Thread-safe semaphores +=head2 C:\perl_tl\perl-5.14.2\lib::Thread::Semaphore, Thread::Semaphore - +Thread-safe semaphores =over 4 @@ -34408,7 +35817,9 @@ above =item METHODS -->new(), ->new(NUMBER), ->down(), ->down(NUMBER), ->up(), ->up(NUMBER) +->new(), ->new(NUMBER), ->down(), ->down(NUMBER), ->down_nb(), +->down_nb(NUMBER), ->down_force(), ->down_force(NUMBER), ->up(), +->up(NUMBER) =item NOTES @@ -34420,26 +35831,8 @@ above =back -=head2 Tie-Memoize::lib::Tie::Memoize, Tie::Memoize - add data to hash when -needed - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item Inheriting from B<Tie::Memoize> - -=item EXAMPLE - -=item BUGS - -=item AUTHOR - -=back - -=head2 Tie::Array - base class for tied arrays +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::Array, Tie::Array - base class for +tied arrays =over 4 @@ -34458,7 +35851,8 @@ SHIFT this, UNSHIFT this, LIST, SPLICE this, offset, length, LIST =back -=head2 Tie::File - Access the lines of a disk file via a Perl array +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::File, Tie::File - Access the lines +of a disk file via a Perl array =over 4 @@ -34526,7 +35920,8 @@ SHIFT this, UNSHIFT this, LIST, SPLICE this, offset, length, LIST =back -=head2 Tie::Handle - base class definitions for tied handles +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::Handle, Tie::Handle - base class +definitions for tied handles =over 4 @@ -34545,8 +35940,8 @@ EOF this, TELL this, SEEK this, offset, whence, DESTROY this =back -=head2 Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for -tied hashes +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::Hash, Tie::Hash, Tie::StdHash, +Tie::ExtraHash - base class definitions for tied hashes =over 4 @@ -34568,7 +35963,8 @@ this, SCALAR this =back -=head2 Tie::Hash::NamedCapture - Named regexp capture buffers +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::Hash::NamedCapture, +Tie::Hash::NamedCapture - Named regexp capture buffers =over 4 @@ -34580,7 +35976,8 @@ this, SCALAR this =back -=head2 Tie::Memoize - add data to hash when needed +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::Memoize, Tie::Memoize - add data to +hash when needed =over 4 @@ -34598,7 +35995,8 @@ this, SCALAR this =back -=head2 Tie::RefHash - use references as hash keys +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::RefHash, Tie::RefHash - use +references as hash keys =over 4 @@ -34614,6 +36012,8 @@ this, SCALAR this =item RELIC SUPPORT +=item LICENSE + =item MAINTAINER =item AUTHOR @@ -34622,8 +36022,8 @@ this, SCALAR this =back -=head2 Tie::Scalar, Tie::StdScalar - base class definitions for tied -scalars +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::Scalar, Tie::Scalar, Tie::StdScalar +- base class definitions for tied scalars =over 4 @@ -34643,7 +36043,8 @@ TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this =back -=head2 Tie::StdHandle - base class definitions for tied handles +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::StdHandle, Tie::StdHandle - base +class definitions for tied handles =over 4 @@ -34653,7 +36054,8 @@ TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this =back -=head2 Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing +=head2 C:\perl_tl\perl-5.14.2\lib::Tie::SubstrHash, Tie::SubstrHash - +Fixed-table-size, fixed-key-length hashing =over 4 @@ -34665,45 +36067,8 @@ TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this =back -=head2 Time-Localib::Time::Local, Time::Local - efficiently compute time -from local and GMT time - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item FUNCTIONS - -=over 4 - -=item C<timelocal()> and C<timegm()> - -=item C<timelocal_nocheck()> and C<timegm_nocheck()> - -=item Year Value Interpretation - -=item Ambiguous Local Times (DST) - -=item Non-Existent Local Times (DST) - -=back - -=item IMPLEMENTATION - -=item BUGS - -=item SUPPORT - -=item COPYRIGHT - -=item AUTHOR - -=back - -=head2 Time::HiRes - High resolution alarm, sleep, gettimeofday, interval -timers +=head2 C:\perl_tl\perl-5.14.2\lib::Time::HiRes, Time::HiRes - High +resolution alarm, sleep, gettimeofday, interval timers =over 4 @@ -34749,7 +36114,8 @@ $flags = 0), clock(), stat, stat FH, stat EXPR =back -=head2 Time::Local - efficiently compute time from local and GMT time +=head2 C:\perl_tl\perl-5.14.2\lib::Time::Local, Time::Local - efficiently +compute time from local and GMT time =over 4 @@ -34767,10 +36133,14 @@ $flags = 0), clock(), stat, stat FH, stat EXPR =item Year Value Interpretation +=item Limits of time_t + =item Ambiguous Local Times (DST) =item Non-Existent Local Times (DST) +=item Negative Epoch Values + =back =item IMPLEMENTATION @@ -34785,7 +36155,8 @@ $flags = 0), clock(), stat, stat FH, stat EXPR =back -=head2 Time::Piece - Object Oriented time objects +=head2 C:\perl_tl\perl-5.14.2\lib::Time::Piece, Time::Piece - Object +Oriented time objects =over 4 @@ -34819,6 +36190,8 @@ $flags = 0), clock(), stat, stat FH, stat EXPR =item Setting $ENV{TZ} in Threads on Win32 +=item Use of epoch seconds + =back =item AUTHOR @@ -34831,7 +36204,8 @@ $flags = 0), clock(), stat, stat FH, stat EXPR =back -=head2 Time::Seconds - a simple API to convert seconds to other date values +=head2 C:\perl_tl\perl-5.14.2\lib::Time::Seconds, Time::Seconds - a simple +API to convert seconds to other date values =over 4 @@ -34849,8 +36223,8 @@ $flags = 0), clock(), stat, stat FH, stat EXPR =back -=head2 Time::gmtime - by-name interface to Perl's built-in gmtime() -function +=head2 C:\perl_tl\perl-5.14.2\lib::Time::gmtime, Time::gmtime - by-name +interface to Perl's built-in gmtime() function =over 4 @@ -34864,8 +36238,8 @@ function =back -=head2 Time::localtime - by-name interface to Perl's built-in localtime() -function +=head2 C:\perl_tl\perl-5.14.2\lib::Time::localtime, Time::localtime - +by-name interface to Perl's built-in localtime() function =over 4 @@ -34879,7 +36253,8 @@ function =back -=head2 Time::tm - internal object used by Time::gmtime and Time::localtime +=head2 C:\perl_tl\perl-5.14.2\lib::Time::tm, Time::tm - internal object +used by Time::gmtime and Time::localtime =over 4 @@ -34891,7 +36266,8 @@ function =back -=head2 UNIVERSAL - base class for ALL classes (blessed references) +=head2 C:\perl_tl\perl-5.14.2\lib::UNIVERSAL, UNIVERSAL - base class for +ALL classes (blessed references) =over 4 @@ -34910,7 +36286,8 @@ METHOD ) >>, C<< eval { VAL->can( METHOD ) } >>, C<VERSION ( [ REQUIRE ] )> =back -=head2 Unicode::Collate - Unicode Collation Algorithm +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Collate, Unicode::Collate - +Unicode Collation Algorithm =over 4 @@ -34924,8 +36301,8 @@ METHOD ) >>, C<< eval { VAL->can( METHOD ) } >>, C<VERSION ( [ REQUIRE ] )> UCA_Version, alternate, backwards, entry, hangul_terminator, ignoreChar, ignoreName, katakana_before_hiragana, level, normalization, overrideCJK, -overrideHangul, preprocess, rearrange, table, undefChar, undefName, -upper_before_lower, variable +overrideHangul, preprocess, rearrange, suppress, table, undefChar, +undefName, upper_before_lower, variable =item Methods for Collation @@ -34949,7 +36326,8 @@ $Collator-E<gt>gsubst($string, $substring, $replacement)> =item Other Methods -C<%old_tailoring = $Collator-E<gt>change(%new_tailoring)>, C<$version = +C<%old_tailoring = $Collator-E<gt>change(%new_tailoring)>, +C<$modified_collator = $Collator-E<gt>change(%new_tailoring)>, C<$version = $Collator-E<gt>version()>, C<UCA_Version()>, C<Base_Unicode_Version()> =back @@ -34968,11 +36346,156 @@ Normalization, Conformance Test Unicode Collation Algorithm - UTS #10, The Default Unicode Collation Element Table (DUCET), The conformance test for the UCA, Hangul Syllable -Type, Unicode Normalization Forms - UAX #15 +Type, Unicode Normalization Forms - UAX #15, Unicode Locale Data Markup +Language (LDML) - UTS #35 + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Collate::CJK::Big5, +Unicode::Collate::CJK::Big5 - weighting CJK Unified Ideographs +for Unicode::Collate + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup +Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Collate::CJK::GB2312, +Unicode::Collate::CJK::GB2312 - weighting CJK Unified Ideographs +for Unicode::Collate + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item CAVEAT + +=item SEE ALSO + +CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup +Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Collate::CJK::JISX0208, +Unicode::Collate::CJK::JISX0208 - weighting JIS KANJI for Unicode::Collate + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +L<Unicode::Collate>, L<Unicode::Collate::Locale> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Collate::CJK::Korean, +Unicode::Collate::CJK::Korean - weighting CJK Unified Ideographs +for Unicode::Collate + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup +Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Collate::CJK::Pinyin, +Unicode::Collate::CJK::Pinyin - weighting CJK Unified Ideographs +for Unicode::Collate + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item CAVEAT + +=item SEE ALSO + +CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup +Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Collate::CJK::Stroke, +Unicode::Collate::CJK::Stroke - weighting CJK Unified Ideographs +for Unicode::Collate + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +CLDR - Unicode Common Locale Data Repository, Unicode Locale Data Markup +Language (LDML) - UTS #35, L<Unicode::Collate>, L<Unicode::Collate::Locale> =back -=head2 Unicode::Normalize - Unicode Normalization Forms +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Collate::Locale, +Unicode::Collate::Locale - Linguistic tailoring for DUCET via +Unicode::Collate + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Constructor + +=item Methods + +C<$Collator-E<gt>getlocale> + +=item A list of tailorable locales + +=back + +=item INSTALL + +=item CAVEAT + +tailoring is not maximum + +=item AUTHOR + +=item SEE ALSO + +Unicode Collation Algorithm - UTS #10, The Default Unicode Collation +Element Table (DUCET), Unicode Locale Data Markup Language (LDML) - UTS +#35, CLDR - Unicode Common Locale Data Repository, L<Unicode::Collate>, +L<Unicode::Normalize> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::Normalize, Unicode::Normalize - +Unicode Normalization Forms =over 4 @@ -34993,7 +36516,11 @@ C<$normalized_string = normalize($form_name, $string)> C<$decomposed_string = decompose($string [, $useCompatMapping])>, C<$reordered_string = reorder($string)>, C<$composed_string = -compose($string)> +compose($string)>, C<($processed, $unprocessed) = +splitOnLastStarter($normalized)>, C<$processed = normalize_partial($form, +$unprocessed)>, C<$processed = NFD_partial($unprocessed)>, C<$processed = +NFC_partial($unprocessed)>, C<$processed = NFKD_partial($unprocessed)>, +C<$processed = NFKC_partial($unprocessed)> =item Quick Check @@ -35039,7 +36566,8 @@ http://www.unicode.org/review/pr-29.html, http://www.unicode.org/notes/tn5/ =back -=head2 Unicode::UCD - Unicode character database +=head2 C:\perl_tl\perl-5.14.2\lib::Unicode::UCD, Unicode::UCD - Unicode +character database =over 4 @@ -35121,7 +36649,7 @@ B<code>, B<full>, B<simple>, B<mapping>, B<status>, B<*>, B<*>, B<turkic> =item B<casespec()> -B<code>, B<lower>, B<title>, B<lower>, B<condition> +B<code>, B<lower>, B<title>, B<upper>, B<condition> =back @@ -35133,6 +36661,12 @@ B<code>, B<lower>, B<title>, B<lower>, B<condition> =over 4 +=item num + +=back + +=over 4 + =item Unicode::UCD::UnicodeVersion =back @@ -35155,8 +36689,8 @@ B<code>, B<lower>, B<title>, B<lower>, B<condition> =back -=head2 User::grent - by-name interface to Perl's built-in getgr*() -functions +=head2 C:\perl_tl\perl-5.14.2\lib::User::grent, User::grent - by-name +interface to Perl's built-in getgr*() functions =over 4 @@ -35170,8 +36704,8 @@ functions =back -=head2 User::pwent - by-name interface to Perl's built-in getpw*() -functions +=head2 C:\perl_tl\perl-5.14.2\lib::User::pwent, User::pwent - by-name +interface to Perl's built-in getpw*() functions =over 4 @@ -35195,55 +36729,8 @@ March 18th, 2000 =back -=head2 VMS-DCLsym, VMS::DCLsym - Perl extension to manipulate DCL symbols - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item Tied hash interface - -=item Object interface - -new, getsym, setsym, delsym, clearcache - -=back - -=item AUTHOR - -=item VERSION - -=item BUGS - -=back - -=head2 VMS-Stdio, VMS::Stdio - standard I/O functions via VMS extensions - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -binmode, flush, getname, remove, rewind, setdef, sync, tmpnam, vmsopen, -alq=INTEGER, bls=INTEGER, ctx=STRING, bin, cvt, nocvt, rec, stm, xplct, -deq=INTEGER, dna=FILESPEC, fop=STRING, ctg, cbt, dfw, dlt, tef, cif, sup, -scf, spl, tmd, tmp, nef, rck, wck, mxv, rwo, pos, rwc, sqo, fsz=INTEGER, -gbc=INTEGER, mbc=INTEGER, mbf=INTEGER, mrs=INTEGER, rat=STRING, cr, blk, -ftn, none, prn, rfm=STRING, fix, stm, stmlf, stmcr, var, vfc, udf, -rop=STRING, asy, cco, cvt, eof, nlk, pmt, pta, rea, rlk, rne, rnf, rrl, -syncsts, tmo, tpt, ulk, wat, rah, wbh, rtv=INTEGER, shr=STRING, del, get, -mse, nil, put, upd, upi, tmo=INTEGER, vmssysopen, waitfh, writeof - -=item REVISION - -=back - -=head2 Win32 - Interfaces to some Win32 API Functions +=head2 C:\perl_tl\perl-5.14.2\lib::Win32, Win32 - Interfaces to some Win32 +API Functions =over 4 @@ -35263,12 +36750,15 @@ 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), -Win32::LoginName(), Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, -SIDTYPE), Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE), +Win32::GetNextAvailDrive(), Win32::GetOSDisplayName(), Win32::GetOSName(), +Win32::GetOSVersion(), Win32::GetShortPathName(PATHNAME), +Win32::GetSystemMetrics(INDEX), Win32::GetProcAddress(INSTANCE, PROCNAME), +Win32::GetProductInfo(OSMAJOR, OSMINOR, SPMAJOR, SPMINOR), +Win32::GetTickCount(), Win32::GuidGen(), Win32::InitiateSystemShutdown, +Win32::IsAdminUser(), Win32::IsWinNT(), Win32::IsWin95(), +Win32::LoadLibrary(LIBNAME), Win32::LoginName(), +Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE), +Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE), Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]]), Win32::NodeName(), Win32::OutputDebugString(STRING), Win32::RegisterServer(LIBRARYNAME), Win32::SetChildShowWindow(SHOWWINDOW), Win32::SetCwd(NEWDIRECTORY), @@ -35279,8 +36769,8 @@ PID), Win32::UnregisterServer(LIBRARYNAME) =back -=head2 Win32API::File - Low-level access to Win32 system API calls for -files/dirs. +=head2 C:\perl_tl\perl-5.14.2\lib::Win32API::File, Win32API::File - +Low-level access to Win32 system API calls for files/dirs. =over 4 @@ -35415,7 +36905,8 @@ C<":SEM_">, C<":PARTITION_">, C<":ALL"> =back -=head2 Win32CORE - Win32 CORE function stubs +=head2 C:\perl_tl\perl-5.14.2\lib::Win32CORE, Win32CORE - Win32 CORE +function stubs =over 4 @@ -35425,37 +36916,52 @@ C<":SEM_">, C<":PARTITION_">, C<":ALL"> =back -=head2 XS-APItest, XS::APItest - Test the perl C API +=head2 C:\perl_tl\perl-5.14.2\lib::XSLoader, XSLoader - Dynamically load C +libraries into Perl code =over 4 -=item SYNOPSIS +=item VERSION -=item ABSTRACT +=item SYNOPSIS =item DESCRIPTION =over 4 -=item EXPORT +=item Migration from C<DynaLoader> + +=item Backward compatible boilerplate + +=back + +=item Order of initialization: early load() -B<print_double>, B<print_long_double>, B<have_long_double>, B<print_nv>, -B<print_iv>, B<print_uv>, B<print_int>, B<print_long>, B<print_float>, -B<call_sv>, B<call_pv>, B<call_method>, B<eval_sv>, B<eval_pv>, -B<require_pv> +=over 4 + +=item The most hairy case =back +=item DIAGNOSTICS + +C<Can't find '%s' symbol in %s>, C<Can't load '%s' for module %s: %s>, +C<Undefined symbols present after loading %s: %s> + +=item LIMITATIONS + +=item BUGS + =item SEE ALSO =item AUTHORS -=item COPYRIGHT AND LICENSE +=item COPYRIGHT & LICENSE =back -=head2 XS-APItest-KeywordRPN, XS::APItest::KeywordRPN - write arithmetic -expressions in RPN +=head2 C:\perl_tl\perl-5.14.2\lib::attributes, attributes - get/set +subroutine or variable attributes =over 4 @@ -35465,35 +36971,155 @@ expressions in RPN =over 4 -=item RPN expression syntax +=item What C<import> does -C<1234>, C<$foo>, I<A> I<B> C<+>, I<A> I<B> C<->, I<A> I<B> C<*>, I<A> I<B> -C</>, I<A> I<B> C<%> +=item Built-in Attributes + +lvalue, method, locked + +=item Available Subroutines + +get, reftype + +=item Package-specific Attribute Handling + +FETCH_I<type>_ATTRIBUTES, MODIFY_I<type>_ATTRIBUTES + +=item Syntax of Attribute Lists =back +=item EXPORTS + +=over 4 + +=item Default exports + +=item Available exports + +=item Export tags defined + +=back + +=item EXAMPLES + +=item MORE EXAMPLES + +=item SEE ALSO + =back +=head2 C:\perl_tl\perl-5.14.2\lib::autodie, autodie - Replace functions +with ones that succeed or die with lexical scope + =over 4 -=item OPERATORS +=item SYNOPSIS + +=item DESCRIPTION -rpn(EXPRESSION), calcrpn VARIABLE { EXPRESSION } +=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, No user hints defined for %s =item BUGS +=over 4 + +=item autodie and string eval + +=item REPORTING BUGS + +=back + +=item FEEDBACK + +=item AUTHOR + +=item LICENSE + +=item SEE ALSO + +=item ACKNOWLEDGEMENTS + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::autodie::exception, 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 -=item COPYRIGHT +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::autodie::exception::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 XS-Typemap, XS::Typemap - module to test the XS typemaps distributed -with perl +=head2 C:\perl_tl\perl-5.14.2\lib::autodie::hints, autodie::hints - Provide +hints about user subroutines to autodie =over 4 @@ -35501,60 +37127,1393 @@ with perl =item DESCRIPTION +=over 4 + +=item Introduction + +=item What are hints? + +=item Example hints + +=back + +=item Manually setting hints from within your program + +=item Adding hints to your module + +=item Insisting on hints + =back =over 4 -=item NOTES +=item Diagnostics + +Attempts to set_hints_for unidentifiable subroutine, fail hints cannot be +provided with either scalar or list hints for %s, %s hint missing for %s + +=item ACKNOWLEDGEMENTS =item AUTHOR +=item LICENSE + +=item SEE ALSO + =back -=head2 XSLoader - Dynamically load C libraries into Perl code +=head2 C:\perl_tl\perl-5.14.2\lib::autouse, autouse - postpone load of +modules until a function is used =over 4 -=item VERSION +=item SYNOPSIS + +=item DESCRIPTION + +=item WARNING + +=item AUTHOR + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::base, base - Establish an ISA +relationship with base classes at compile time + +=over 4 =item SYNOPSIS =item DESCRIPTION +=item DIAGNOSTICS + +Base class package "%s" is empty, Class 'Foo' tried to inherit from itself + +=item HISTORY + +=item CAVEATS + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::bigint, bigint - Transparent BigInteger +support for Perl + =over 4 -=item Migration from C<DynaLoader> +=item SYNOPSIS -=item Backward compatible boilerplate +=item DESCRIPTION + +=over 4 + +=item use integer vs. use bigint + +=item Options + +a or accuracy, p or precision, t or trace, hex, oct, l, lib, try or only, v +or version + +=item Math Library + +=item Internal Format + +=item Sign + +=item Methods + +inf(), NaN(), e, PI, bexp(), bpi(), upgrade(), in_effect() + +=item MATH LIBRARY + +=item Caveat =back -=item Order of initialization: early load() +=item CAVEATS + +in_effect(), hex()/oct() + +=item MODULES USED + +=item EXAMPLES + +=item LICENSE + +=item SEE ALSO + +=item AUTHORS + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::bignum, bignum - Transparent BigNumber +support for Perl =over 4 -=item The most hairy case +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Options + +a or accuracy, p or precision, t or trace, l or lib, hex, oct, v or version + +=item Methods + +=item Caveats + +inf(), NaN(), e, PI(), bexp(), bpi(), upgrade(), in_effect() + +=item Math Library + +=item INTERNAL FORMAT + +=item SIGN =back -=item DIAGNOSTICS +=item CAVEATS -C<Can't find '%s' symbol in %s>, C<Can't load '%s' for module %s: %s>, -C<Undefined symbols present after loading %s: %s>, -C<XSLoader::load('Your::Module', $Your::Module::VERSION)> +in_effect(), hex()/oct() + +=item MODULES USED + +=item EXAMPLES + +=item LICENSE + +=item SEE ALSO + +=item AUTHORS + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::bigrat, bigrat - Transparent +BigNumber/BigRational support for Perl + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Modules Used + +=item Math Library + +=item Sign + +=item Methods + +inf(), NaN(), e, PI, bexp(), bpi(), upgrade(), in_effect() + +=item MATH LIBRARY + +=item Caveat + +=item Options + +a or accuracy, p or precision, t or trace, l or lib, hex, oct, v or version + +=back + +=item CAVEATS + +in_effect(), hex()/oct() + +=item EXAMPLES + +=item LICENSE + +=item SEE ALSO + +=item AUTHORS + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::blib, blib - Use MakeMaker's uninstalled +version of a package + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item BUGS + +=item AUTHOR + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::bytes, bytes - Perl pragma to force byte +semantics rather than character semantics + +=over 4 + +=item NOTICE + +=item SYNOPSIS + +=item DESCRIPTION =item LIMITATIONS +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::charnames, charnames - access to Unicode +character names and named character sequences; also define character names + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item ALIASES + +=item CUSTOM ALIASES + +=item charnames::viacode(I<code>) + +=item charnames::string_vianame(I<name>) + +=item charnames::vianame(I<name>) + +=item CUSTOM TRANSLATORS + =item BUGS +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::constant, constant - Perl pragma to +declare constants + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item NOTES + +=over 4 + +=item List constants + +=item Defining multiple constants at once + +=item Magic constants + +=back + +=item TECHNICAL NOTES + +=item CAVEATS + =item SEE ALSO +=item BUGS + =item AUTHORS =item COPYRIGHT & LICENSE =back +=head2 C:\perl_tl\perl-5.14.2\lib::deprecate, deprecate - Perl pragma for +deprecating the core version of a module + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item EXPORT + +=back + +=item SEE ALSO + +=item AUTHOR + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::diagnostics, diagnostics, splain - +produce verbose warning diagnostics + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item The C<diagnostics> Pragma + +=item The I<splain> Program + +=back + +=item EXAMPLES + +=item INTERNALS + +=item BUGS + +=item AUTHOR + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::encoding, encoding - allows you to write +your script in non-ascii or non-utf8 + +=over 4 + +=item SYNOPSIS + +=item ABSTRACT + +=over 4 + +=item Literal Conversions + +=item PerlIO layers for C<STD(IN|OUT)> + +=item Implicit upgrading for byte strings + +=item Side effects + +=back + +=item FEATURES THAT REQUIRE 5.8.1 + +"NON-EUC" doublebyte encodings, tr//, DATA pseudo-filehandle + +=item USAGE + +use encoding [I<ENCNAME>] ;, use encoding I<ENCNAME> [ STDIN =E<gt> +I<ENCNAME_IN> ...] ;, use encoding I<ENCNAME> Filter=E<gt>1;, no encoding; + +=item The Filter Option + +=over 4 + +=item Filter-related changes at Encode version 1.87 + +=back + +=item CAVEATS + +=over 4 + +=item NOT SCOPED + +=item DO NOT MIX MULTIPLE ENCODINGS + +=item tr/// with ranges + +Legend of characters above + +=back + +=item EXAMPLE - Greekperl + +=item KNOWN PROBLEMS + +literals in regex that are longer than 127 bytes, EBCDIC, format, Thread +safety + +=over 4 + +=item The Logic of :locale + +=back + +=item HISTORY + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::encoding::warnings, encoding::warnings - +Warn on implicit encoding conversions + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Overview of the problem + +=item Detecting the problem + +=item Solving the problem + +Upgrade both sides to unicode-strings, Downgrade both sides to +byte-strings, Specify the encoding for implicit byte-string upgrading, +PerlIO layers for B<STDIN> and B<STDOUT>, Literal conversions, Implicit +upgrading for byte-strings + +=back + +=item CAVEATS + +=back + +=over 4 + +=item SEE ALSO + +=item AUTHORS + +=item COPYRIGHT + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::feature, feature - Perl pragma to enable +new features + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Lexical effect + +=item C<no feature> + +=item The 'switch' feature + +=item The 'say' feature + +=item the 'state' feature + +=item the 'unicode_strings' feature + +=back + +=item FEATURE BUNDLES + +=item IMPLICIT LOADING + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::fields, fields - compile-time class +fields + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +new, phash + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::filetest, filetest - Perl pragma to +control the filetest permission operators + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Consider this carefully + +=item The "access" sub-pragma + +=item Limitation with regard to C<_> + +=back + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::if, if - C<use> a Perl module if a +condition holds + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item BUGS + +=item AUTHOR + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::inc::latest, inc::latest - use modules +bundled in inc/ if they are newer than installed ones + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Special notes on bundling + +=back + +=item USAGE + +=over 4 + +=item Author-mode + +loaded_modules(), write(), bundle_module() + +=item As bundled in inc/ + +=back + +=item AUTHOR + +=item COPYRIGHT + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::integer, integer - Perl pragma to use +integer arithmetic instead of floating point + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::less, less - perl pragma to request less +of something + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item FOR MODULE AUTHORS + +=over 4 + +=item C<< BOOLEAN = less->of( FEATURE ) >> + +=item C<< FEATURES = less->of() >> + +=back + +=item CAVEATS + +This probably does nothing, This works only on 5.10+ + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::lib, lib - manipulate @INC at compile +time + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Adding directories to @INC + +=item Deleting directories from @INC + +=item Restoring original @INC + +=back + +=item CAVEATS + +=item NOTES + +=item SEE ALSO + +=item AUTHOR + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::locale, locale - Perl pragma to use and +avoid POSIX locales for built-in operations + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::mro, mro - Method Resolution Order + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item OVERVIEW + +=item The C3 MRO + +=over 4 + +=item What is C3? + +=item How does C3 work + +=back + +=item Functions + +=over 4 + +=item mro::get_linear_isa($classname[, $type]) + +=item mro::set_mro ($classname, $type) + +=item mro::get_mro($classname) + +=item mro::get_isarev($classname) + +=item mro::is_universal($classname) + +=item mro::invalidate_all_method_caches() + +=item mro::method_changed_in($classname) + +=item mro::get_pkg_gen($classname) + +=item next::method + +=item next::can + +=item maybe::next::method + +=back + +=item SEE ALSO + +=over 4 + +=item The original Dylan paper + +L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html> + +=item Pugs + +=item Parrot + +L<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>, +L<http://use.perl.org/~autrijus/journal/25768> + +=item Python 2.3 MRO related links + +L<http://www.python.org/2.3/mro.html>, +L<http://www.python.org/2.2.2/descrintro.html#mro> + +=item C3 for TinyCLOS + +L<http://www.call-with-current-continuation.org/eggs/c3.html> + +=item Class::C3 + +L<Class::C3> + +=back + +=item AUTHOR + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::open, open - perl pragma to set default +PerlIO layers for input and output + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item NONPERLIO FUNCTIONALITY + +=item IMPLEMENTATION DETAILS + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::ops, ops - Perl pragma to restrict +unsafe operations when compiling + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::overload, overload - Package for +overloading Perl operations + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Fundamentals + +=item Overloadable Operations + +C<not>, C<neg>, C<++>, C<-->, I<Assignments>, I<Non-mutators with a mutator +variant>, C<int>, I<String, numeric, boolean, and regexp conversions>, +I<Iteration>, I<File tests>, I<Matching>, I<Dereferencing>, I<Special> + +=item Magic Autogeneration + +=item Special Keys for C<use overload> + +defined, but FALSE, C<undef>, TRUE + +=item How Perl Chooses an Operator Implementation + +=item Losing Overloading + +=item Inheritance and Overloading + +Method names in the C<use overload> directive, Overloading of an operation +is inherited by derived classes + +=item Run-time Overloading + +=item Public Functions + +overload::StrVal(arg), overload::Overloaded(arg), overload::Method(obj,op) + +=item Overloading Constants + +integer, float, binary, q, qr + +=back + +=item IMPLEMENTATION + +=item COOKBOOK + +=over 4 + +=item Two-face Scalars + +=item Two-face References + +=item Symbolic Calculator + +=item I<Really> Symbolic Calculator + +=back + +=item AUTHOR + +=item SEE ALSO + +=item DIAGNOSTICS + +Odd number of arguments for overload::constant, `%s' is not an overloadable +type, `%s' is not a code reference + +=item BUGS AND PITFALLS + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::overloading, overloading - perl pragma +to lexically control overloading + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +C<no overloading>, C<no overloading @ops>, C<use overloading>, C<use +overloading @ops> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::parent, 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 C:\perl_tl\perl-5.14.2\lib::re, re - Perl pragma to alter regular +expression behaviour + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item 'taint' mode + +=item 'eval' mode + +=item '/flags' mode + +=item 'debug' mode + +=item 'Debug' mode + +Compile related options, COMPILE, PARSE, OPTIMISE, TRIEC, DUMP, Execute +related options, EXECUTE, MATCH, TRIEE, INTUIT, Extra debugging options, +EXTRA, BUFFERS, TRIEM, STATE, STACK, OPTIMISEM, OFFSETS, OFFSETSDBG, Other +useful flags, ALL, All, MORE, More + +=item Exportable Functions + +is_regexp($ref), regexp_pattern($ref), regmust($ref), regname($name,$all), +regnames($all), regnames_count() + +=back + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::sigtrap, sigtrap - Perl pragma to enable +simple signal handling + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item OPTIONS + +=over 4 + +=item SIGNAL HANDLERS + +B<stack-trace>, B<die>, B<handler> I<your-handler> + +=item SIGNAL LISTS + +B<normal-signals>, B<error-signals>, B<old-interface-signals> + +=item OTHER + +B<untrapped>, B<any>, I<signal>, I<number> + +=back + +=item EXAMPLES + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::sort, sort - perl pragma to control +sort() behaviour + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item CAVEATS + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::strict, strict - Perl pragma to restrict +unsafe constructs + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +C<strict refs>, C<strict vars>, C<strict subs> + +=item HISTORY + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::subs, subs - Perl pragma to predeclare +sub names + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::threads, threads - Perl +interpreter-based threads + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +$thr = threads->create(FUNCTION, ARGS), $thr->join(), $thr->detach(), +threads->detach(), threads->self(), $thr->tid(), threads->tid(), "$thr", +threads->object($tid), threads->yield(), threads->list(), +threads->list(threads::all), threads->list(threads::running), +threads->list(threads::joinable), $thr1->equal($thr2), async BLOCK;, +$thr->error(), $thr->_handle(), threads->_handle() + +=item EXITING A THREAD + +threads->exit(), threads->exit(status), die(), exit(status), use threads +'exit' => 'threads_only', threads->create({'exit' => 'thread_only'}, ...), +$thr->set_thread_exit_only(boolean), threads->set_thread_exit_only(boolean) + +=item THREAD STATE + +$thr->is_running(), $thr->is_joinable(), $thr->is_detached(), +threads->is_detached() + +=item THREAD CONTEXT + +=over 4 + +=item Explicit context + +=item Implicit context + +=item $thr->wantarray() + +=item threads->wantarray() + +=back + +=item THREAD STACK SIZE + +threads->get_stack_size();, $size = $thr->get_stack_size();, $old_size = +threads->set_stack_size($new_size);, use threads ('stack_size' => VALUE);, +$ENV{'PERL5_ITHREADS_STACK_SIZE'}, threads->create({'stack_size' => VALUE}, +FUNCTION, ARGS), $thr2 = $thr1->create(FUNCTION, ARGS) + +=item THREAD SIGNALLING + +$thr->kill('SIG...'); + +=item WARNINGS + +Perl exited with active threads:, Thread creation failed: pthread_create +returned #, Thread # terminated abnormally: .., Using minimum thread stack +size of #, Thread creation failed: pthread_attr_setstacksize(I<SIZE>) +returned 22 + +=item ERRORS + +This Perl not built to support threads, Cannot change stack size of an +existing thread, Cannot signal threads without safe signals, Unrecognized +signal name: .. + +=item BUGS AND LIMITATIONS + +Thread-safe modules, Using non-thread-safe modules, Memory consumption, +Current working directory, Environment variables, Parent-child threads, +Creating threads inside special blocks, Unsafe signals, Perl has been built +with C<PERL_OLD_SIGNALS> (see C<perl -V>), The environment variable +C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">), The +module L<Perl::Unsafe::Signals> is used, Returning closures from threads, +Returning objects from threads, END blocks in threads, Open directory +handles, Perl Bugs and the CPAN Version of L<threads> + +=item REQUIREMENTS + +=item SEE ALSO + +=item AUTHOR + +=item LICENSE + +=item ACKNOWLEDGEMENTS + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::threads::shared, threads::shared - Perl +extension for sharing data structures between threads + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item EXPORT + +=item FUNCTIONS + +share VARIABLE, 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 + +=item NOTES + +=item BUGS AND LIMITATIONS + +=item SEE ALSO + +=item AUTHOR + +=item LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::utf8, utf8 - Perl pragma to +enable/disable UTF-8 (or UTF-EBCDIC) in source code + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Utility functions + +$num_octets = utf8::upgrade($string), $success = utf8::downgrade($string[, +FAIL_OK]), utf8::encode($string), $success = utf8::decode($string), $flag = +utf8::is_utf8(STRING), $flag = utf8::valid(STRING) + +=back + +=item BUGS + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::vars, vars - Perl pragma to predeclare +global variable names (obsolete) + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::version, version - Perl extension for +Version Objects + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item TYPES OF VERSION OBJECTS + +Decimal Versions, Dotted Decimal Versions + +=item DECLARING VERSIONS + +=over 4 + +=item How to convert a module from decimal to dotted-decimal + +=item How to C<declare()> a dotted-decimal version + +=back + +=item PARSING AND COMPARING VERSIONS + +=over 4 + +=item How to C<parse()> a version + +=item How to check for a legal version string + +C<is_lax()>, C<is_strict()> + +=item How to compare version objects + +=back + +=item OBJECT METHODS + +=over 4 + +=item is_alpha() + +=item is_qv() + +=item normal() + +=item numify() + +=item stringify() + +=back + +=item EXPORTED FUNCTIONS + +=over 4 + +=item qv() + +=item is_lax() + +=item is_strict() + +=back + +=item AUTHOR + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::version::Internals, version::Internals - +Perl extension for Version Objects + +=over 4 + +=item DESCRIPTION + +=item WHAT IS A VERSION? + +Decimal Versions, Dotted-Decimal Versions + +=over 4 + +=item Decimal Versions + +=item Dotted-Decimal Versions + +=item Alpha Versions + +=item Regular Expressions for Version Parsing + +C<$version::LAX>, C<$version::STRICT>, v1.234.5 + +=back + +=item IMPLEMENTATION DETAILS + +=over 4 + +=item Equivalence between Decimal and Dotted-Decimal Versions + +=item Quoting Rules + +=item What about v-strings? + +=item Version Object Internals + +original, qv, alpha, version + +=item Replacement UNIVERSAL::VERSION + +=back + +=item USAGE DETAILS + +=over 4 + +=item Using modules that use version.pm + +Decimal versions always work, Dotted-Decimal version work sometimes + +=item Object Methods + +new(), qv(), Normal Form, Numification, Stringification, Comparison +operators, Logical Operators + +=back + +=item AUTHOR + +=item SEE ALSO + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::version::Requirements, +Version::Requirements - a set of version requirements for a CPAN dist + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item new + +=item add_minimum + +=item add_maximum + +=item add_exclusion + +=item exact_version + +=item add_requirements + +=item accepts_module + +=item clear_requirement + +=item required_modules + +=item clone + +=item is_simple + +=item is_finalized + +=item finalize + +=item as_string_hash + +=item from_string_hash + +=back + +=item AUTHOR + +=item COPYRIGHT AND LICENSE + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::vmsish, vmsish - Perl pragma to control +VMS-specific language features + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +C<vmsish status>, C<vmsish exit>, C<vmsish time>, C<vmsish hushed> + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::warnings, warnings - Perl pragma to +control optional warnings + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +use warnings::register, warnings::enabled(), warnings::enabled($category), +warnings::enabled($object), warnings::fatal_enabled(), +warnings::fatal_enabled($category), warnings::fatal_enabled($object), +warnings::warn($message), warnings::warn($category, $message), +warnings::warn($object, $message), warnings::warnif($message), +warnings::warnif($category, $message), warnings::warnif($object, $message), +warnings::register_categories(@names) + +=back + +=head2 C:\perl_tl\perl-5.14.2\lib::warnings::register, warnings::register - +warnings import function + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + =head1 AUXILIARY DOCUMENTATION Here should be listed all the extra programs' documentation, but they diff --git a/Master/tlpkg/tlperl/lib/pods/perltodo.pod b/Master/tlpkg/tlperl/lib/pods/perltodo.pod index 0a03bf41752..de0e373b468 100644 --- a/Master/tlpkg/tlperl/lib/pods/perltodo.pod +++ b/Master/tlpkg/tlperl/lib/pods/perltodo.pod @@ -5,7 +5,7 @@ perltodo - Perl TO-DO List =head1 DESCRIPTION This is a list of wishes for Perl. The most up to date version of this file -is at http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/pod/perltodo.pod +is at L<http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/pod/perltodo.pod> The tasks we think are smaller or easier are listed first. Anyone is welcome to work on any of these, but it's a good idea to first contact @@ -15,9 +15,8 @@ prefer. Whilst patches to make the list shorter are most welcome, ideas to add to the list are also encouraged. Check the perl5-porters archives for past -ideas, and any discussion about them. One set of archives may be found at: - - http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ +ideas, and any discussion about them. One set of archives may be found at +L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/> What can we offer you in return? Fame, fortune, and everlasting glory? Maybe not, but if your patch is incorporated, then we'll add your name to the @@ -26,14 +25,10 @@ programming languages offer you 1 line of immortality? =head1 Tasks that only need Perl knowledge -=head2 Improve Porting/cmpVERSION.pl to work from git tags - -See F<Porting/release_managers_guide.pod> for a bit more detail. - =head2 Migrate t/ from custom TAP generation Many tests below F<t/> still generate TAP by "hand", rather than using library -functions. As explained in L<perlhack/Writing a test>, tests in F<t/> are +functions. As explained in L<perlhack/TESTING>, tests in F<t/> are written in a particular way to test that more complex constructions actually work before using them routinely. Hence they don't use C<Test::More>, but instead there is an intentionally simpler library, F<t/test.pl>. However, @@ -43,24 +38,6 @@ any of these tests, one at a time, is a useful thing TODO. The subdirectories F<base>, F<cmd> and F<comp>, that contain the most basic tests, should be excluded from this task. -=head2 Test that regen.pl was run - -There are various generated files shipped with the perl distribution, for -things like header files generate from data. The generation scripts are -written in perl, and all can be run by F<regen.pl>. However, because they're -written in perl, we can't run them before we've built perl. We can't run them -as part of the F<Makefile>, because changing files underneath F<make> confuses -it completely, and we don't want to run them automatically anyway, as they -change files shipped by the distribution, something we seek not do to. - -If someone changes the data, but forgets to re-run F<regen.pl> then the -generated files are out of sync. It would be good to have a test in -F<t/porting> that checks that the generated files are in sync, and fails -otherwise, to alert someone before they make a poor commit. I suspect that this -would require adapting the scripts run from F<regen.pl> to have dry-run -options, and invoking them with these, or by refactoring them into a library -that does the generation, which can be called by the scripts, and by the test. - =head2 Automate perldelta generation The perldelta file accompanying each release summaries the major changes. @@ -150,14 +127,6 @@ do so. Test it with older perl releases, and fix the problems you find. To make a minimal perl distribution, it's useful to look at F<t/lib/commonsense.t>. -=head2 Move dual-life pod/*.PL into ext - -Nearly all the dual-life modules have been moved to F<ext>. However, we -still need to move F<pod/*.PL> into their respective directories -in F<ext/>. They're referenced by (at least) C<plextract> in F<Makefile.SH> -and C<utils> in F<win32/Makefile> and F<win32/makefile.ml>, and listed -explicitly in F<win32/pod.mak>, F<vms/descrip_mms.template> and F<utils.lst> - =head2 POSIX memory footprint Ilya observed that use POSIX; eats memory like there's no tomorrow, and at @@ -201,7 +170,7 @@ The F<installman> script is slow. All it is doing text processing, which we're told is something Perl is good at. So it would be nice to know what it is doing that is taking so much CPU, and where possible address it. -=head2 enable lexical enabling/disabling of inidvidual warnings +=head2 enable lexical enabling/disabling of individual warnings Currently, warnings can only be enabled or disabled by category. There are times when it would be useful to quash a single warning, not a @@ -261,7 +230,7 @@ to do this manually are roughly =item * do a normal C<Configure>, but include Devel::Cover as a module to install -(see F<INSTALL> for how to do this) +(see L<INSTALL> for how to do this) =item * @@ -338,7 +307,8 @@ visibility just to symbols declared in that file. It would be good to extend F<makedef.pl> to support this format, and to provide a means within C<Configure> to enable it. This would allow Unix users to test that the export list is correct, and to build a perl that does not pollute the global -namespace with private symbols. +namespace with private symbols, and will fail in the same way as msvc or mingw +builds or when using PERL_DL_NONLAZY=1. =head2 Cross-compile support @@ -466,7 +436,7 @@ The way @INC is laid out by default, one cannot upgrade core (dual-life) modules without overwriting files. This causes problems for binary package builders. One possible proposal is laid out in this message: -L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2002-04/msg02380.html>. +L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2002-04/msg02380.html> =head2 -Duse32bit* @@ -474,7 +444,7 @@ Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall. On these systems, it might be the default compilation mode, and there is currently no guarantee that passing no use64bitall option to the Configure process will build a 32bit perl. Implementing -Duse32bit* -options would be nice for perl 5.12. +options would be nice for perl 5.14. =head2 Profile Perl - am I hot or not? @@ -554,7 +524,7 @@ bug is fixed in the VC8 and VC9 CRTs (but, of course, the directory may still not actually be writable if access is indeed denied by DACLs). For the chdir() issue, see ActiveState bug #74552: -http://bugs.activestate.com/show_bug.cgi?id=74552 +L<http://bugs.activestate.com/show_bug.cgi?id=74552> Therefore, DACLs should be checked both for consistency across CRTs and for the correct answer. @@ -777,7 +747,7 @@ of running Perl code inside the signal handler context. (With all the dangers of things like C<malloc> corruption that that currently offers us) For more information see the thread starting with this message: -http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2008-03/msg00305.html +L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2008-03/msg00305.html> =head2 autovivification @@ -940,7 +910,7 @@ be C<*$> instead. (This is changed in F<opcode.pl>) Currently C<$foo ~~ $object> will die with the message "Smart matching a non-overloaded object breaks encapsulation". It would be nice to allow -to bypass this by using explictly the syntax C<$foo ~~ %$object> or +to bypass this by using explicitly the syntax C<$foo ~~ %$object> or C<$foo ~~ @$object>. =head2 error reporting of [$a ; $b] @@ -958,7 +928,7 @@ 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 +L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2008-09/msg00573.html> =head2 lexicals used only once @@ -977,10 +947,13 @@ years for this discrepancy. =head2 UTF-8 revamp -The handling of Unicode is unclean in many places. For example, the regexp -engine matches in Unicode semantics whenever the string or the pattern is -flagged as UTF-8, but that should not be dependent on an internal storage -detail of the string. +The handling of Unicode is unclean in many places. In the regex engine +there are especially many problems. The swash data structure could be +replaced my something better. Inversion lists and maps are likely +candidates. The whole Unicode database could be placed in-core for a +huge speed-up. Only minimal work was done on the optimizer when utf8 +was added, with the result that the synthetic start class often will +fail to narrow down the possible choices when given non-Latin1 input. =head2 Properly Unicode safe tokeniser and pads. @@ -1053,7 +1026,8 @@ arrays as alternations. With it, C</P/w> would be roughly equivalent to: do { local $"='|'; /\b(?:P)\b/ } -See L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2007-01/msg00400.html> +See +L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2007-01/msg00400.html> for the discussion. =head2 optional optimizer @@ -1131,7 +1105,8 @@ See also L</"Extend PerlIO and PerlIO::Scalar">. The peephole optimiser converts constants used for hash key lookups to shared hash key scalars. Under ithreads, something is undoing this work. -See http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2007-09/msg00793.html +See +L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2007-09/msg00793.html> =head2 Store the current pad in the OP slab allocator @@ -1160,7 +1135,8 @@ Note that the slab allocator allocates ops downwards in memory, so one would have to actually "allocate" the ops in reverse-execution order to get them contiguous in memory in execution order. -See http://www.nntp.perl.org/group/perl.perl5.porters/2007/12/msg131975.html +See +L<http://www.nntp.perl.org/group/perl.perl5.porters/2007/12/msg131975.html> Note that running this copy, and then freeing all the old location ops would cause their slabs to be freed, which would eliminate possible memory wastage if @@ -1243,10 +1219,16 @@ combines the code in pp_entersub, pp_leavesub. This should probably be done 1st in XS, and using B::Generate to patch the new OP into the optrees. +=head2 Add C<00dddd> + +It has been proposed that octal constants be specifiable through the syntax +C<0oddddd>, parallel to the existing construct to specify hex constants +C<0xddddd> + =head1 Big projects Tasks that will get your name mentioned in the description of the "Highlights -of 5.12" +of 5.14" =head2 make ithreads more robust @@ -1255,7 +1237,8 @@ Generally make ithreads more robust. See also L</iCOW> This task is incremental - even a little bit of work on it will help, and will be greatly appreciated. -One bit would be to write the missing code in sv.c:Perl_dirp_dup. +One bit would be to determine how to clone directory handles on systems +without a C<fchdir> function (in sv.c:Perl_dirp_dup). Fix Perl_sv_dup, et al so that threads can return objects. @@ -1269,11 +1252,6 @@ it would be a good thing. Fix (or rewrite) the implementation of the C</(?{...})/> closures. -=head2 A re-entrant regexp engine - -This will allow the use of a regex from inside (?{ }), (??{ }) and -(?(?{ })|) constructs. - =head2 Add class set operations to regexp engine Apparently these are quite useful. Anyway, Jeffery Friedl wants them. diff --git a/Master/tlpkg/tlperl/lib/pods/perltrap.pod b/Master/tlpkg/tlperl/lib/pods/perltrap.pod index b5f09351669..99e25c8d490 100644 --- a/Master/tlpkg/tlperl/lib/pods/perltrap.pod +++ b/Master/tlpkg/tlperl/lib/pods/perltrap.pod @@ -497,7 +497,7 @@ of a variable, or as a delimiter for any kind of quote construct. Double darn. $a = ("foo bar"); - $b = q baz; + $b = q baz ; print "a is $a, b is $b\n"; # perl4 prints: a is foo bar, b is baz @@ -665,7 +665,7 @@ are to used around the name. # perl4 prints: 2 # perl5 fails with syntax error - @ = (1..3); + @a = (1..3); print "$#{a}"; # perl4 prints: {a} @@ -704,7 +704,7 @@ tries to be more precise. For example, on a Solaris Sparc: # Perl5 prints: 7.373504 - 7.375039999999999614 + 7.373503999999999614 Notice how the first result looks better in Perl 5. @@ -960,14 +960,15 @@ being required. =item * Comma operator in scalar context gives scalar context to args The comma operator in a scalar context is now guaranteed to give a -scalar context to its arguments. +scalar context to its last argument. It gives scalar or void context +to any preceding arguments, depending on circumstances. @y= ('a','b','c'); $x = (1, 2, @y); print "x = $x\n"; - # Perl4 prints: x = c # Thinks list context interpolates list - # Perl5 prints: x = 3 # Knows scalar uses length of list + # Perl4 prints: x = c # Interpolates array @y into the list + # Perl5 prints: x = 3 # Evaluates array @y in scalar context =item * C<sprintf()> prototyped as C<($;@)> diff --git a/Master/tlpkg/tlperl/lib/pods/perltru64.pod b/Master/tlpkg/tlperl/lib/pods/perltru64.pod index 6961a0e7c17..618c5748d09 100644 --- a/Master/tlpkg/tlperl/lib/pods/perltru64.pod +++ b/Master/tlpkg/tlperl/lib/pods/perltru64.pod @@ -106,7 +106,7 @@ and then using the BerkeleyDB module from CPAN instead of DB_File. The BerkeleyDB works with Berkeley DB versions 2.* or greater. The Berkeley DB 4.1.25 has been tested with Tru64 V5.1A and found -to work. The latest Berkeley DB can be found from F<http://www.sleepycat.com>. +to work. The latest Berkeley DB can be found from L<http://www.sleepycat.com>. =head2 64-bit Perl on Tru64 diff --git a/Master/tlpkg/tlperl/lib/pods/perlunicode.pod b/Master/tlpkg/tlperl/lib/pods/perlunicode.pod index 140d1340b20..d77c40cbbde 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlunicode.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlunicode.pod @@ -11,7 +11,8 @@ implement the Unicode standard or the accompanying technical reports from cover to cover, Perl does support many Unicode features. People who want to learn to use Unicode in Perl, should probably read -the L<Perl Unicode tutorial, perlunitut|perlunitut>, before reading +the L<Perl Unicode tutorial, perlunitut|perlunitut> and +L<perluniintro>, before reading this reference document. Also, the use of Unicode may present security issues that aren't obvious. @@ -19,24 +20,27 @@ Read L<Unicode Security Considerations|http://www.unicode.org/reports/tr36>. =over 4 +=item Safest if you "use feature 'unicode_strings'" + +In order to preserve backward compatibility, Perl does not turn +on full internal Unicode support unless the pragma +C<use feature 'unicode_strings'> is specified. (This is automatically +selected if you use C<use 5.012> or higher.) Failure to do this can +trigger unexpected surprises. See L</The "Unicode Bug"> below. + +This pragma doesn't affect I/O, and there are still several places +where Unicode isn't fully supported, such as in filenames. + =item Input and Output Layers Perl knows when a filehandle uses Perl's internal Unicode encodings (UTF-8, or UTF-EBCDIC if in EBCDIC) if the filehandle is opened with -the ":utf8" layer. Other encodings can be converted to Perl's +the ":encoding(utf8)" layer. Other encodings can be converted to Perl's encoding on input or from Perl's encoding on output by use of the ":encoding(...)" layer. See L<open>. To indicate that Perl source itself is in UTF-8, use C<use utf8;>. -=item Regular Expressions - -The regular expression compiler produces polymorphic opcodes. That is, -the pattern adapts to the data and automatically switches to the Unicode -character scheme when presented with data that is internally encoded in -UTF-8, or instead uses a traditional byte scheme when presented with -byte data. - =item C<use utf8> still needed to enable UTF-8/UTF-EBCDIC in scripts As a compatibility measure, the C<use utf8> pragma must be explicitly @@ -71,20 +75,31 @@ See L</"Byte and Character Semantics"> for more details. Beginning with version 5.6, Perl uses logically-wide characters to represent strings internally. -In future, Perl-level operations will be expected to work with -characters rather than bytes. - -However, as an interim compatibility measure, Perl aims to -provide a safe migration path from byte semantics to character -semantics for programs. For operations where Perl can unambiguously -decide that the input data are characters, Perl switches to -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>, and -absent a C<use feature 'unicode_strings'> pragma, Perl currently uses US-ASCII +Starting in Perl 5.14, Perl-level operations work with +characters rather than bytes within the scope of a +C<L<use feature 'unicode_strings'|feature>> (or equivalently +C<use 5.012> or higher). (This is not true if bytes have been +explicitly requested by C<L<use bytes|bytes>>, nor necessarily true +for interactions with the platform's operating system.) + +For earlier Perls, and when C<unicode_strings> is not in effect, Perl +provides a fairly safe environment that can handle both types of +semantics in programs. For operations where Perl can unambiguously +decide that the input data are characters, Perl switches to 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. + +When C<use locale> is in effect (which overrides +C<use feature 'unicode_strings'> in the same scope), Perl uses the +semantics associated +with the current locale. Otherwise, Perl uses the platform's native +byte semantics for characters whose code points are less than 256, and +Unicode semantics for those greater than 255. On EBCDIC platforms, this +is almost seamless, as the EBCDIC code pages that Perl handles are +equivalent to Unicode's first 256 code points. (The exception is that +EBCDIC regular expression case-insensitive matching rules are not as +as robust as Unicode's.) But on ASCII platforms, Perl uses US-ASCII (or Basic Latin in Unicode terminology) byte semantics, meaning that characters whose ordinal numbers are in the range 128 - 255 are undefined except for their ordinal numbers. This means that none have case (upper and lower), nor are any @@ -98,31 +113,12 @@ character data. Such data may come from filehandles, from calls to external programs, from information provided by the system (such as %ENV), or from literals and constants in the source text. -The C<bytes> pragma will always, regardless of platform, force byte -semantics in a particular lexical scope. See L<bytes>. - -The C<use feature 'unicode_strings'> pragma is intended to always, regardless -of platform, force character (Unicode) semantics in a particular lexical scope. -In release 5.12, it is partially implemented, applying only to case changes. -See L</The "Unicode Bug"> below. - The C<utf8> pragma is primarily a compatibility device that enables recognition of UTF-(8|EBCDIC) in literals encountered by the parser. Note that this pragma is only required while Perl defaults to byte semantics; when character semantics become the default, this pragma may become a no-op. See L<utf8>. -Unless explicitly stated, Perl operators use character semantics -for Unicode data and byte semantics for non-Unicode data. -The decision to use character semantics is made transparently. If -input data comes from a Unicode source--for example, if a character -encoding layer is added to a filehandle or a literal Unicode -string constant appears in a program--character semantics apply. -Otherwise, byte semantics are in effect. The C<bytes> pragma should -be used to force byte semantics on Unicode data, and the C<use feature -'unicode_strings'> pragma to force Unicode semantics on byte data (though in -5.12 it isn't fully implemented). - If strings operating under byte semantics and strings with Unicode character data are concatenated, the new string will have character semantics. This can cause surprises: See L</BUGS>, below. @@ -266,8 +262,9 @@ complement B<and> the full character-wide bit complement. You can define your own mappings to be used in C<lc()>, C<lcfirst()>, C<uc()>, and C<ucfirst()> (or their double-quoted string inlined -versions such as C<\U>). -See L</"User-Defined Case Mappings"> for more details. +versions such as C<\U>). See +L<User-Defined Case-Mappings|/"User-Defined Case Mappings (for serious hackers only)"> +for more details. =back @@ -281,14 +278,14 @@ And finally, C<scalar reverse()> reverses by character rather than by byte. =head2 Unicode Character Properties -Most Unicode character properties are accessible by using regular expressions. -They are used (like bracketed character classes) by using the C<\p{}> "matches -property" construct and the C<\P{}> negation, "doesn't match property". - -Note that the only time that Perl considers a sequence of individual code +(The only time that Perl considers a sequence of individual code points as a single logical character is in the C<\X> construct, already mentioned above. Therefore "character" in this discussion means a single -Unicode code point. +Unicode code point.) + +Very nearly all Unicode character properties are accessible through +regular expressions by using the C<\p{}> "matches property" construct +and the C<\P{}> "doesn't match property" for its negation. For instance, C<\p{Uppercase}> matches any single character with the Unicode "Uppercase" property, while C<\p{L}> matches any character with a @@ -300,11 +297,11 @@ Uppercase property value is True, and C<\P{Uppercase}> matches any character whose Uppercase property value is False, and they could have been written as C<\p{Uppercase=True}> and C<\p{Uppercase=False}>, respectively. -This formality is needed when properties are not binary, that is if they can +This formality is needed when properties are not binary; that is, if they can take on more values than just True and False. For example, the Bidi_Class (see -L</"Bidirectional Character Types"> below), can take on a number of different +L</"Bidirectional Character Types"> below), can take on several different values, such as Left, Right, Whitespace, and others. To match these, one needs -to specify the property name (Bidi_Class), and the value being matched against +to specify the property name (Bidi_Class), AND the value being matched against (Left, Right, etc.). This is done, as in the examples above, by having the two components separated by an equal sign (or interchangeably, a colon), like C<\p{Bidi_Class: Left}>. @@ -317,9 +314,9 @@ below, in which you may omit the property name and the equals or colon separator. Most Unicode character properties have at least two synonyms (or aliases if you -prefer), a short one that is easier to type, and a longer one which is more -descriptive and hence it is easier to understand what it means. Thus the "L" -and "Letter" above are equivalent and can be used interchangeably. Likewise, +prefer): a short one that is easier to type and a longer one that is more +descriptive and hence easier to understand. Thus the "L" and "Letter" properties +above are equivalent and can be used interchangeably. Likewise, "Upper" is a synonym for "Uppercase", and we could have written C<\p{Uppercase}> equivalently as C<\p{Upper}>. Also, there are typically various synonyms for the values the property can be. For binary properties, @@ -330,24 +327,43 @@ General_Category property, "L" means "Letter", but for the Bidi_Class property, "L" means "Left". A complete list of properties and synonyms is in L<perluniprops>. -Upper/lower case differences in the property names and values are irrelevant, +Upper/lower case differences in property names and values are irrelevant; thus C<\p{Upper}> means the same thing as C<\p{upper}> or even C<\p{UpPeR}>. Similarly, you can add or subtract underscores anywhere in the middle of a word, so that these are also equivalent to C<\p{U_p_p_e_r}>. And white space is irrelevant adjacent to non-word characters, such as the braces and the equals -or colon separators so C<\p{ Upper }> and C<\p{ Upper_case : Y }> are -equivalent to these as well. In fact, in most cases, white space and even -hyphens can be added or deleted anywhere. So even C<\p{ Up-per case = Yes}> is +or colon separators, so C<\p{ Upper }> and C<\p{ Upper_case : Y }> are +equivalent to these as well. In fact, white space and even +hyphens can usually be added or deleted anywhere. So even C<\p{ Up-per case = Yes}> is equivalent. All this is called "loose-matching" by Unicode. The few places -where stricter matching is employed is in the middle of numbers, and the Perl +where stricter matching is used is in the middle of numbers, and in the Perl extension properties that begin or end with an underscore. Stricter matching -cares about white space (except adjacent to the non-word characters) and +cares about white space (except adjacent to non-word characters), hyphens, and non-interior underscores. You can also use negation in both C<\p{}> and C<\P{}> by introducing a caret (^) between the first brace and the property name: C<\p{^Tamil}> is equal to C<\P{Tamil}>. +Almost all properties are immune to case-insensitive matching. That is, +adding a C</i> regular expression modifier does not change what they +match. There are two sets that are affected. +The first set is +C<Uppercase_Letter>, +C<Lowercase_Letter>, +and C<Titlecase_Letter>, +all of which match C<Cased_Letter> under C</i> matching. +And the second set is +C<Uppercase>, +C<Lowercase>, +and C<Titlecase>, +all of which match C<Cased> under C</i> matching. +This set also includes its subsets C<PosixUpper> and C<PosixLower> both +of which under C</i> matching match C<PosixAlpha>. +(The difference between these sets is that some things, such as Roman +numerals, come in both upper and lower case so they are C<Cased>, but aren't considered +letters, so they aren't C<Cased_Letter>s.) + =head3 B<General_Category> Every Unicode character is assigned a general category, which is the "most @@ -404,24 +420,19 @@ Here are the short and long forms of the General Category properties: Zp Paragraph_Separator C Other - Cc Control (also Cntrl) + Cc Control (also Cntrl) Cf Format - Cs Surrogate (not usable) + Cs Surrogate Co Private_Use Cn Unassigned Single-letter properties match all characters in any of the two-letter sub-properties starting with the same letter. -C<LC> and C<L&> are special cases, which are both aliases for the set consisting of everything matched by C<Ll>, C<Lu>, and C<Lt>. - -Because Perl hides the need for the user to understand the internal -representation of Unicode characters, there is no need to implement -the somewhat messy concept of surrogates. C<Cs> is therefore not -supported. +C<LC> and C<L&> are special: both are aliases for the set consisting of everything matched by C<Ll>, C<Lu>, and C<Lt>. =head3 B<Bidirectional Character Types> -Because scripts differ in their directionality (Hebrew is +Because scripts differ in their directionality (Hebrew and Arabic are written right to left, for example) Unicode supplies these properties in the Bidi_Class class: @@ -453,9 +464,9 @@ written right to left. =head3 B<Scripts> -The world's languages are written in a number of scripts. This sentence +The world's languages are written in many different scripts. This sentence (unless you're reading it in translation) is written in Latin, while Russian is -written in Cyrllic, and Greek is written in, well, Greek; Japanese mainly in +written in Cyrillic, and Greek is written in, well, Greek; Japanese mainly in Hiragana or Katakana. There are many more. The Unicode Script property gives what script a given character is in, @@ -480,25 +491,30 @@ characters. The difference between scripts and blocks is that the concept of scripts is closer to natural languages, while the concept of blocks is more of an artificial grouping based on groups of Unicode characters with consecutive ordinal values. For example, the "Basic Latin" -block is all characters whose ordinals are between 0 and 127, inclusive, in +block is all characters whose ordinals are between 0 and 127, inclusive; in other words, the ASCII characters. The "Latin" script contains some letters -from this block as well as several more, like "Latin-1 Supplement", +from this as well as several other blocks, like "Latin-1 Supplement", "Latin Extended-A", etc., but it does not contain all the characters from -those blocks. It does not, for example, contain digits, because digits are -shared across many scripts. Digits and similar groups, like punctuation, are in -the script called C<Common>. There is also a script called C<Inherited> for -characters that modify other characters, and inherit the script value of the -controlling character. +those blocks. It does not, for example, contain the digits 0-9, because +those digits are shared across many scripts. The digits 0-9 and similar groups, +like punctuation, are in the script called C<Common>. There is also a +script called C<Inherited> for characters that modify other characters, +and inherit the script value of the controlling character. (Note that +there are several different sets of digits in Unicode that are +equivalent to 0-9 and are matchable by C<\d> in a regular expression. +If they are used in a single language only, they are in that language's +script. Only sets are used across several languages are in the +C<Common> script.) For more about scripts versus blocks, see UAX#24 "Unicode Script Property": L<http://www.unicode.org/reports/tr24> The Script property is likely to be the one you want to use when processing -natural language; the Block property may be useful in working with the nuts and -bolts of Unicode. +natural language; the Block property may occasionally be useful in working +with the nuts and bolts of Unicode. Block names are matched in the compound form, like C<\p{Block: Arrows}> or -C<\p{Blk=Hebrew}>. Unlike most other properties only a few block names have a +C<\p{Blk=Hebrew}>. Unlike most other properties, only a few block names have a Unicode-defined short name. But Perl does provide a (slight) shortcut: You can say, for example C<\p{In_Arrows}> or C<\p{In_Hebrew}>. For backwards compatibility, the C<In> prefix may be omitted if there is no naming conflict @@ -523,10 +539,10 @@ doesn't. =back -Some people just prefer to always use C<\p{Block: foo}> and C<\p{Script: bar}> -instead of the shortcuts, for clarity, and because they can't remember the -difference between 'In' and 'Is' anyway (or aren't confident that those who -eventually will read their code will know). +Some people prefer to always use C<\p{Block: foo}> and C<\p{Script: bar}> +instead of the shortcuts, whether for clarity, because they can't remember the +difference between 'In' and 'Is' anyway, or they aren't confident that those who +eventually will read their code will know that difference. A complete list of blocks and their shortcuts is in L<perluniprops>. @@ -536,12 +552,12 @@ There are many more properties than the very basic ones described here. A complete list is in L<perluniprops>. Unicode defines all its properties in the compound form, so all single-form -properties are Perl extensions. A number of these are just synonyms for the -Unicode ones, but some are genunine extensions, including a couple that are in +properties are Perl extensions. Most of these are just synonyms for the +Unicode ones, but some are genuine extensions, including several that are in the compound form. And quite a few of these are actually recommended by Unicode (in L<http://www.unicode.org/reports/tr18>). -This section gives some details on all the extensions that aren't synonyms for +This section gives some details on all extensions that aren't synonyms for compound-form Unicode properties (for those, you'll have to refer to the L<Unicode Standard|http://www.unicode.org/reports/tr44>. @@ -561,6 +577,11 @@ This matches any C<\p{Alphabetic}> or C<\p{Decimal_Number}> character. This matches any of the 1_114_112 Unicode code points. It is a synonym for C<\p{All}>. +=item B<C<\p{ASCII}>> + +This matches any of the 128 characters in the US-ASCII character set, +which is a subset of Unicode. + =item B<C<\p{Assigned}>> This matches any assigned code point; that is, any code point whose general @@ -579,47 +600,47 @@ To understand the use of this rarely used property=value combination, it is necessary to know some basics about decomposition. Consider a character, say H. It could appear with various marks around it, such as an acute accent, or a circumflex, or various hooks, circles, arrows, -I<etc.>, above, below, to one side and/or the other, etc. There are many +I<etc.>, above, below, to one side or the other, etc. There are many possibilities among the world's languages. The number of combinations is astronomical, and if there were a character for each combination, it would soon exhaust Unicode's more than a million possible characters. So Unicode took a different approach: there is a character for the base H, and a -character for each of the possible marks, and they can be combined variously +character for each of the possible marks, and these can be variously combined to get a final logical character. So a logical character--what appears to be a single character--can be a sequence of more than one individual characters. -This is called an "extended grapheme cluster". (Perl furnishes the C<\X> -construct to match such sequences.) +This is called an "extended grapheme cluster"; Perl furnishes the C<\X> +regular expression construct to match such sequences. But Unicode's intent is to unify the existing character set standards and -practices, and a number of pre-existing standards have single characters that +practices, and several pre-existing standards have single characters that mean the same thing as some of these combinations. An example is ISO-8859-1, which has quite a few of these in the Latin-1 range, an example being "LATIN CAPITAL LETTER E WITH ACUTE". Because this character was in this pre-existing standard, Unicode added it to its repertoire. But this character is considered -by Unicode to be equivalent to the sequence consisting of first the character -"LATIN CAPITAL LETTER E", then the character "COMBINING ACUTE ACCENT". +by Unicode to be equivalent to the sequence consisting of the character +"LATIN CAPITAL LETTER E" followed by the character "COMBINING ACUTE ACCENT". "LATIN CAPITAL LETTER E WITH ACUTE" is called a "pre-composed" character, and -the equivalence with the sequence is called canonical equivalence. All +its equivalence with the sequence is called canonical equivalence. All pre-composed characters are said to have a decomposition (into the equivalent -sequence) and the decomposition type is also called canonical. +sequence), and the decomposition type is also called canonical. However, many more characters have a different type of decomposition, a "compatible" or "non-canonical" decomposition. The sequences that form these decompositions are not considered canonically equivalent to the pre-composed character. An example, again in the Latin-1 range, is the "SUPERSCRIPT ONE". -It is kind of like a regular digit 1, but not exactly; its decomposition +It is somewhat like a regular digit 1, but not exactly; its decomposition into the digit 1 is called a "compatible" decomposition, specifically a "super" decomposition. There are several such compatibility decompositions (see L<http://www.unicode.org/reports/tr44>), including one -called "compat" which means some miscellaneous type of decomposition -that doesn't fit into the decomposition categories that Unicode has chosen. +called "compat", which means some miscellaneous type of decomposition +that doesn't fit into the decomposition categories that Unicode has chosen. Note that most Unicode characters don't have a decomposition, so their decomposition type is "None". -Perl has added the C<Non_Canonical> type, for your convenience, to mean any of -the compatibility decompositions. +For your convenience, Perl has added the C<Non_Canonical> decomposition +type to mean any of the several compatibility decompositions. =item B<C<\p{Graph}>> @@ -628,10 +649,10 @@ that on a printer would cause ink to be used. =item B<C<\p{HorizSpace}>> -This is the same as C<\h> and C<\p{Blank}>: A character that changes the +This is the same as C<\h> and C<\p{Blank}>: a character that changes the spacing horizontally. -=item B<C<\p{In=*}>> +=item B<C<\p{In=*}>> This is a synonym for C<\p{Present_In=*}> @@ -647,56 +668,11 @@ This is the same as C<\w>, restricted to ASCII, namely C<[A-Za-z0-9_]> Mnemonic: Perl's (original) word. -=item B<C<\p{PosixAlnum}>> - -This matches any alphanumeric character in the ASCII range, namely -C<[A-Za-z0-9]>. - -=item B<C<\p{PosixAlpha}>> - -This matches any alphabetic character in the ASCII range, namely C<[A-Za-z]>. - -=item B<C<\p{PosixBlank}>> - -This matches any blank character in the ASCII range, namely C<S<[ \t]>>. +=item B<C<\p{Posix...}>> -=item B<C<\p{PosixCntrl}>> - -This matches any control character in the ASCII range, namely C<[\x00-\x1F\x7F]> - -=item B<C<\p{PosixDigit}>> - -This matches any digit character in the ASCII range, namely C<[0-9]>. - -=item B<C<\p{PosixGraph}>> - -This matches any graphical character in the ASCII range, namely C<[\x21-\x7E]>. - -=item B<C<\p{PosixLower}>> - -This matches any lowercase character in the ASCII range, namely C<[a-z]>. - -=item B<C<\p{PosixPrint}>> - -This matches any printable character in the ASCII range, namely C<[\x20-\x7E]>. -These are the graphical characters plus SPACE. - -=item B<C<\p{PosixPunct}>> - -This matches any punctuation character in the ASCII range, namely -C<[\x21-\x2F\x3A-\x40\x5B-\x60\x7B-\x7E]>. These are the -graphical characters that aren't word characters. Note that the Posix standard -includes in its definition of punctuation, those characters that Unicode calls -"symbols." - -=item B<C<\p{PosixSpace}>> - -This matches any space character in the ASCII range, namely -C<S<[ \f\n\r\t\x0B]>> (the last being a vertical tab). - -=item B<C<\p{PosixUpper}>> - -This matches any uppercase character in the ASCII range, namely C<[A-Z]>. +There are several of these, which are equivalents using the C<\p> +notation for Posix classes and are described in +L<perlrecharclass/POSIX Character Classes>. =item B<C<\p{Present_In: *}>> (Short: C<\p{In=*}>) @@ -725,13 +701,12 @@ Some non-Perl implementations of the Age property may change its meaning to be the same as the Perl Present_In property; just be aware of that. Another confusion with both these properties is that the definition is not -that the code point has been assigned, but that the meaning of the code point -has been determined. This is because 66 code points will always be -unassigned, and, so the Age for them is the Unicode version the decision to -make them so was made in. For example, C<U+FDD0> is to be permanently +that the code point has been I<assigned>, but that the meaning of the code point +has been I<determined>. This is because 66 code points will always be +unassigned, and so the Age for them is the Unicode version in which the decision +to make them so was made. For example, C<U+FDD0> is to be permanently unassigned to a character, and the decision to do that was made in version 3.1, -so C<\p{Age=3.1}> matches this character and C<\p{Present_In: 3.1}> and up -matches as well. +so C<\p{Age=3.1}> matches this character, as also does C<\p{Present_In: 3.1}> and up. =item B<C<\p{Print}>> @@ -742,7 +717,7 @@ This matches any character that is graphical or blank, except controls. This is the same as C<\s>, including beyond ASCII. Mnemonic: Space, as modified by Perl. (It doesn't include the vertical tab -which both the Posix standard and Unicode consider to be space.) +which both the Posix standard and Unicode consider white space.) =item B<C<\p{VertSpace}>> @@ -750,7 +725,13 @@ This is the same as C<\v>: A character that changes the spacing vertically. =item B<C<\p{Word}>> -This is the same as C<\w>, including beyond ASCII. +This is the same as C<\w>, including over 100_000 characters beyond ASCII. + +=item B<C<\p{XPosix...}>> + +There are several of these, which are the standard Posix classes +extended to the full Unicode range. They are described in +L<perlrecharclass/POSIX Character Classes>. =back @@ -772,6 +753,16 @@ C<\p> or C<\P> construct. Note that the effect is compile-time and immutable once defined. +However, the subroutines are passed a single parameter, which is 0 if +case-sensitive matching is in effect and non-zero if caseless matching +is in effect. The subroutine may return different values depending on +the value of the flag, and one set of values will immutably be in effect +for all case-sensitive matches, and the other set for all case-insensitive +matches. + +Note that if the regular expression is tainted, then Perl will die rather +than calling the subroutine, where the name of the subroutine is +determined by the tainted data. The subroutines must return a specially-formatted string, with one or more newline-separated lines. Each line must be one of the following: @@ -821,7 +812,7 @@ For example, to define a property that covers both the Japanese syllabaries (hiragana and katakana), you can define sub InKana { - return <<END; + return <<END; 3040\t309F 30A0\t30FF END @@ -833,7 +824,7 @@ Now you can use C<\p{InKana}> and C<\P{InKana}>. You could also have used the existing block property names: sub InKana { - return <<'END'; + return <<'END'; +utf8::InHiragana +utf8::InKatakana END @@ -844,7 +835,7 @@ not the raw block ranges: in other words, you want to remove the non-characters: sub InKana { - return <<'END'; + return <<'END'; +utf8::InHiragana +utf8::InKatakana -utf8::IsCn @@ -854,7 +845,7 @@ the non-characters: The negation is useful for defining (surprise!) negated classes. sub InNotKana { - return <<'END'; + return <<'END'; !utf8::InHiragana -utf8::InKatakana +utf8::IsCn @@ -872,46 +863,193 @@ two (or more) classes. } It's important to remember not to use "&" for the first set; that -would be intersecting with nothing (resulting in an empty set). +would be intersecting with nothing, resulting in an empty set. + +=head2 User-Defined Case Mappings (for serious hackers only) + +B<This featured is deprecated and is scheduled to be removed in Perl +5.16.> +The CPAN module L<Unicode::Casing> provides better functionality +without the drawbacks described below. -=head2 User-Defined Case Mappings +You can define your own mappings to be used in C<lc()>, +C<lcfirst()>, C<uc()>, and C<ucfirst()> (or their string-inlined versions, +C<\L>, C<\l>, C<\U>, and C<\u>). The mappings are currently only valid +on strings encoded in UTF-8, but see below for a partial workaround for +this restriction. -You can also define your own mappings to be used in the lc(), -lcfirst(), uc(), and ucfirst() (or their string-inlined versions). The principle is similar to that of user-defined character -properties: to define subroutines -with names like C<ToLower> (for lc() and lcfirst()), C<ToTitle> (for -the first character in ucfirst()), and C<ToUpper> (for uc(), and the -rest of the characters in ucfirst()). +properties: define subroutines that do the mappings. +C<ToLower> is used for C<lc()>, C<\L>, C<lcfirst()>, and C<\l>; C<ToTitle> for +C<ucfirst()> and C<\u>; and C<ToUpper> for C<uc()> and C<\U>. -The string returned by the subroutines needs to be two hexadecimal numbers -separated by two tabulators: the two numbers being, respectively, the source -code point and the destination code point. For example: +C<ToUpper()> should look something like this: sub ToUpper { - return <<END; - 0061\t\t0041 + return <<END; + 0061\t007A\t0041 + 0101\t\t0100 END } -defines an uc() mapping that causes only the character "a" -to be mapped to "A"; all other characters will remain unchanged. - -(For serious hackers only) The above means you have to furnish a complete -mapping; you can't just override a couple of characters and leave the rest -unchanged. You can find all the mappings in the directory -C<$Config{privlib}>/F<unicore/To/>. The mapping data is returned as the -here-document, and the C<utf8::ToSpecFoo> are special exception mappings -derived from <$Config{privlib}>/F<unicore/SpecialCasing.txt>. The "Digit" and +This sample C<ToUpper()> has the effect of mapping "a-z" to "A-Z", 0x101 +to 0x100, and all other characters map to themselves. The first +returned line means to map the code point at 0x61 ("a") to 0x41 ("A"), +the code point at 0x62 ("b") to 0x42 ("B"), ..., 0x7A ("z") to 0x5A +("Z"). The second line maps just the code point 0x101 to 0x100. Since +there are no other mappings defined, all other code points map to +themselves. + +This mechanism is not well behaved as far as affecting other packages +and scopes. All non-threaded programs have exactly one uppercasing +behavior, one lowercasing behavior, and one titlecasing behavior in +effect for utf8-encoded strings for the duration of the program. Each +of these behaviors is irrevocably determined the first time the +corresponding function is called to change a utf8-encoded string's case. +If a corresponding C<To-> function has been defined in the package that +makes that first call, the mapping defined by that function will be the +mapping used for the duration of the program's execution across all +packages and scopes. If no corresponding C<To-> function has been +defined in that package, the standard official mapping will be used for +all packages and scopes, and any corresponding C<To-> function anywhere +will be ignored. Threaded programs have similar behavior. If the +program's casing behavior has been decided at the time of a thread's +creation, the thread will inherit that behavior. But, if the behavior +hasn't been decided, the thread gets to decide for itself, and its +decision does not affect other threads nor its creator. + +As shown by the example above, you have to furnish a complete mapping; +you can't just override a couple of characters and leave the rest +unchanged. You can find all the official mappings in the directory +C<$Config{privlib}>F</unicore/To/>. The mapping data is returned as the +here-document. The C<utf8::ToSpecI<Foo>> hashes in those files are special +exception mappings derived from +C<$Config{privlib}>F</unicore/SpecialCasing.txt>. (The "Digit" and "Fold" mappings that one can see in the directory are not directly -user-accessible, one can use either the C<Unicode::UCD> module, or just match -case-insensitively (that's when the "Fold" mapping is used). +user-accessible, one can use either the L<Unicode::UCD> module, or just match +case-insensitively, which is what uses the "Fold" mapping. Neither are user +overridable.) + +If you have many mappings to change, you can take the official mapping data, +change by hand the affected code points, and place the whole thing into your +subroutine. But this will only be valid on Perls that use the same Unicode +version. Another option would be to have your subroutine read the official +mapping files and overwrite the affected code points. -The mappings will only take effect on scalars that have been marked as having -Unicode characters, for example by using C<utf8::upgrade()>. -Old byte-style strings are not affected. +If you have only a few mappings to change, starting in 5.14 you can use the +following trick, here illustrated for Turkish. -The mappings are in effect for the package they are defined in. + use Config; + use charnames ":full"; + + sub ToUpper { + my $official = do "$Config{privlib}/unicore/To/Upper.pl"; + $utf8::ToSpecUpper{'i'} = + "\N{LATIN CAPITAL LETTER I WITH DOT ABOVE}"; + return $official; + } + +This takes the official mappings and overrides just one, for "LATIN SMALL +LETTER I". The keys to the hash must be the bytes that form the UTF-8 +(on EBCDIC platforms, UTF-EBCDIC) of the character, as illustrated by +the inverse function. + + sub ToLower { + my $official = do $lower; + $utf8::ToSpecLower{"\xc4\xb0"} = "i"; + return $official; + } + +This example is for an ASCII platform, and C<\xc4\xb0> is the string of +bytes that together form the UTF-8 that represents C<\N{LATIN CAPITAL +LETTER I WITH DOT ABOVE}>, C<U+0130>. You can avoid having to figure out +these bytes, and at the same time make it work on all platforms by +instead writing: + + sub ToLower { + my $official = do $lower; + my $sequence = "\N{LATIN CAPITAL LETTER I WITH DOT ABOVE}"; + utf8::encode($sequence); + $utf8::ToSpecLower{$sequence} = "i"; + return $official; + } + +This works because C<utf8::encode()> takes the single character and +converts it to the sequence of bytes that constitute it. Note that we took +advantage of the fact that C<"i"> is the same in UTF-8 or UTF_EBCIDIC as not; +otherwise we would have had to write + + $utf8::ToSpecLower{$sequence} = "\N{LATIN SMALL LETTER I}"; + +in the ToLower example, and in the ToUpper example, use + + my $sequence = "\N{LATIN SMALL LETTER I}"; + utf8::encode($sequence); + +A big caveat to the above trick and to this whole mechanism in general, +is that they work only on strings encoded in UTF-8. You can partially +get around this by using C<use subs>. (But better to just convert to +use L<Unicode::Casing>.) For example: +(The trick illustrated here does work in earlier releases, but only if all the +characters you want to override have ordinal values of 256 or higher, or +if you use the other tricks given just below.) + +The mappings are in effect only for the package they are defined in, and only +on scalars that have been marked as having Unicode characters, for example by +using C<utf8::upgrade()>. Although probably not advisable, you can +cause the mappings to be used globally by importing into C<CORE::GLOBAL> +(see L<CORE>). + +You can partially get around the restriction that the source strings +must be in utf8 by using C<use subs> (or by importing into C<CORE::GLOBAL>) by: + + use subs qw(uc ucfirst lc lcfirst); + + sub uc($) { + my $string = shift; + utf8::upgrade($string); + return CORE::uc($string); + } + + sub lc($) { + my $string = shift; + utf8::upgrade($string); + + # Unless an I is before a dot_above, it turns into a dotless i. + # (The character class with the combining classes matches non-above + # marks following the I. Any number of these may be between the 'I' and + # the dot_above, and the dot_above will still apply to the 'I'. + use charnames ":full"; + $string =~ + s/I + (?! [^\p{ccc=0}\p{ccc=Above}]* \N{COMBINING DOT ABOVE} ) + /\N{LATIN SMALL LETTER DOTLESS I}/gx; + + # But when the I is followed by a dot_above, remove the + # dot_above so the end result will be i. + $string =~ s/I + ([^\p{ccc=0}\p{ccc=Above}]* ) + \N{COMBINING DOT ABOVE} + /i$1/gx; + return CORE::lc($string); + } + +These examples (also for Turkish) make sure the input is in UTF-8, and then +call the corresponding official function, which will use the C<ToUpper()> and +C<ToLower()> functions you have defined. +(For Turkish, there are other required functions: C<ucfirst>, C<lcfirst>, +and C<ToTitle>. These are very similar to the ones given above.) + +The reason this is only a partial fix is that it doesn't affect the C<\l>, +C<\L>, C<\u>, and C<\U> case-change operations in regular expressions, +which still require the source to be encoded in utf8 (see L</The "Unicode +Bug">). (Again, use L<Unicode::Casing> instead.) + +The C<lc()> example shows how you can add context-dependent casing. Note +that context-dependent casing suffers from the problem that the string +passed to the casing function may not have sufficient context to make +the proper choice. Also, it will not be called for C<\l>, C<\L>, C<\u>, +and C<\U>. =head2 Character Encodings for Input and Output @@ -919,10 +1057,10 @@ See L<Encode>. =head2 Unicode Regular Expression Support Level -The following list of Unicode support for regular expressions describes -all the features currently supported. The references to "Level N" +The following list of Unicode supported features for regular expressions describes +all features currently directly supported by core Perl. The references to "Level N" and the section numbers refer to the Unicode Technical Standard #18, -"Unicode Regular Expressions", version 11, in May 2005. +"Unicode Regular Expressions", version 13, from August 2008. =over 4 @@ -930,36 +1068,41 @@ and the section numbers refer to the Unicode Technical Standard #18, Level 1 - Basic Unicode Support - RL1.1 Hex Notation - done [1] - RL1.2 Properties - done [2][3] - RL1.2a Compatibility Properties - done [4] - RL1.3 Subtraction and Intersection - MISSING [5] - RL1.4 Simple Word Boundaries - done [6] - RL1.5 Simple Loose Matches - done [7] - RL1.6 Line Boundaries - MISSING [8] - RL1.7 Supplementary Code Points - done [9] + RL1.1 Hex Notation - done [1] + RL1.2 Properties - done [2][3] + RL1.2a Compatibility Properties - done [4] + RL1.3 Subtraction and Intersection - MISSING [5] + RL1.4 Simple Word Boundaries - done [6] + RL1.5 Simple Loose Matches - done [7] + RL1.6 Line Boundaries - MISSING [8][9] + RL1.7 Supplementary Code Points - done [10] [1] \x{...} [2] \p{...} \P{...} - [3] supports not only minimal list, but all Unicode character - properties (see L</Unicode Character Properties>) + [3] supports not only minimal list, but all Unicode character + properties (see L</Unicode Character Properties>) [4] \d \D \s \S \w \W \X [:prop:] [:^prop:] [5] can use regular expression look-ahead [a] or - user-defined character properties [b] to emulate set operations + user-defined character properties [b] to emulate set + operations [6] \b \B - [7] note that Perl does Full case-folding in matching (but with bugs), - not Simple: for example U+1F88 is equivalent to U+1F00 U+03B9, - not with 1F80. This difference matters mainly for certain Greek - capital letters with certain modifiers: the Full case-folding - decomposes the letter, while the Simple case-folding would map - it to a single character. - [8] should do ^ and $ also on U+000B (\v in C), FF (\f), CR (\r), - CRLF (\r\n), NEL (U+0085), LS (U+2028), and PS (U+2029); - should also affect <>, $., and script line numbers; - should not split lines within CRLF [c] (i.e. there is no empty - line between \r and \n) - [9] UTF-8/UTF-EBDDIC used in perl allows not only U+10000 to U+10FFFF - but also beyond U+10FFFF [d] + [7] note that Perl does Full case-folding in matching (but with + bugs), not Simple: for example U+1F88 is equivalent to + U+1F00 U+03B9, not with 1F80. This difference matters + mainly for certain Greek capital letters with certain + modifiers: the Full case-folding decomposes the letter, + while the Simple case-folding would map it to a single + character. + [8] should do ^ and $ also on U+000B (\v in C), FF (\f), CR + (\r), CRLF (\r\n), NEL (U+0085), LS (U+2028), and PS + (U+2029); should also affect <>, $., and script line + numbers; should not split lines within CRLF [c] (i.e. there + is no empty line between \r and \n) + [9] Linebreaking conformant with UAX#14 "Unicode Line Breaking + Algorithm" is available through the Unicode::LineBreaking + module. + [10] UTF-8/UTF-EBDDIC used in Perl allows not only U+10000 to + U+10FFFF but also beyond U+10FFFF [a] You can mimic class subtraction using lookahead. For example, what UTS#18 might write as @@ -985,9 +1128,6 @@ UTS#18 grouping, intersection, union, and removal (subtraction) syntax. [c] Try the C<:crlf> layer (see L<PerlIO>). -[d] U+FFFF will currently generate a warning message if 'utf8' warnings are - enabled - =item * Level 2 - Extended Unicode Support @@ -1004,8 +1144,7 @@ Level 2 - Extended Unicode Support [12] have \X but we don't have a "Grapheme Cluster Mode" [14] see UAX#29, Word Boundaries [15] see UAX#21 "Case Mappings" - [16] have \N{...} but neither compute names of CJK Ideographs - and Hangul Syllables nor use a loose match [e] + [16] missing loose match [e] [e] C<\N{...}> allows namespaces (see L<charnames>). @@ -1027,11 +1166,12 @@ Level 3 - Tailored Support [17] see UAX#10 "Unicode Collation Algorithms" [18] have Unicode::Collate but not integrated to regexes - [19] have (?<=x) and (?=x), but look-aheads or look-behinds should see - outside of the target substring - [20] need insensitive matching for linguistic features other than case; - for example, hiragana to katakana, wide and narrow, simplified Han - to traditional Han (see UTR#30 "Character Foldings") + [19] have (?<=x) and (?=x), but look-aheads or look-behinds + should see outside of the target substring + [20] need insensitive matching for linguistic features other + than case; for example, hiragana to katakana, wide and + narrow, simplified Han to traditional Han (see UTR#30 + "Character Foldings") =back @@ -1046,27 +1186,26 @@ numbers. To use these numbers, various encodings are needed. UTF-8 -UTF-8 is a variable-length (1 to 6 bytes, current character allocations -require 4 bytes), byte-order independent encoding. For ASCII (and we -really do mean 7-bit ASCII, not another 8-bit encoding), UTF-8 is -transparent. +UTF-8 is a variable-length (1 to 4 bytes), byte-order independent +encoding. For ASCII (and we really do mean 7-bit ASCII, not another +8-bit encoding), UTF-8 is transparent. The following table is from Unicode 3.2. - Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte + Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte - U+0000..U+007F 00..7F + U+0000..U+007F 00..7F U+0080..U+07FF * C2..DF 80..BF - U+0800..U+0FFF E0 * A0..BF 80..BF + U+0800..U+0FFF E0 * A0..BF 80..BF U+1000..U+CFFF E1..EC 80..BF 80..BF U+D000..U+D7FF ED 80..9F 80..BF U+D800..U+DFFF +++++++ utf16 surrogates, not legal utf8 +++++++ U+E000..U+FFFF EE..EF 80..BF 80..BF - U+10000..U+3FFFF F0 * 90..BF 80..BF 80..BF - U+40000..U+FFFFF F1..F3 80..BF 80..BF 80..BF - U+100000..U+10FFFF F4 80..8F 80..BF 80..BF + U+10000..U+3FFFF F0 * 90..BF 80..BF 80..BF + U+40000..U+FFFFF F1..F3 80..BF 80..BF 80..BF + U+100000..U+10FFFF F4 80..8F 80..BF 80..BF -Note the gaps before several of the byte entries above marked by '*'. These are +Note the gaps marked by "*" before several of the byte entries above. These are caused by legal UTF-8 avoiding non-shortest encodings: it is technically possible to UTF-8-encode a single code point in different ways, but that is explicitly forbidden, and the shortest possible encoding should always be used @@ -1085,6 +1224,16 @@ As you can see, the continuation bytes all begin with "10", and the leading bits of the start byte tell how many bytes there are in the encoded character. +The original UTF-8 specification allowed up to 6 bytes, to allow +encoding of numbers up to 0x7FFF_FFFF. Perl continues to allow those, +and has extended that up to 13 bytes to encode code points up to what +can fit in a 64-bit word. However, Perl will warn if you output any of +these as being non-portable; and under strict UTF-8 input protocols, +they are forbidden. + +The Unicode non-character code points are also disallowed in UTF-8 in +"open interchange". See L</Non-character code points>. + =item * UTF-EBCDIC @@ -1098,8 +1247,10 @@ UTF-16, UTF-16BE, UTF-16LE, Surrogates, and BOMs (Byte Order Marks) The followings items are mostly for reference and general Unicode knowledge, Perl doesn't use these constructs internally. -UTF-16 is a 2 or 4 byte encoding. The Unicode code points -C<U+0000..U+FFFF> are stored in a single 16-bit unit, and the code +Like UTF-8, UTF-16 is a variable-width encoding, but where +UTF-8 uses 8-bit code units, UTF-16 uses 16-bit code units. +All code points occupy either 2 or 4 bytes in UTF-16: code points +C<U+0000..U+FFFF> are stored in a single 16-bit unit, and code points C<U+10000..U+10FFFF> in two 16-bit units. The latter case is using I<surrogates>, the first 16-bit unit being the I<high surrogate>, and the second being the I<low surrogate>. @@ -1109,16 +1260,12 @@ range of Unicode code points in pairs of 16-bit units. The I<high surrogates> are the range C<U+D800..U+DBFF> and the I<low surrogates> are the range C<U+DC00..U+DFFF>. The surrogate encoding is - $hi = ($uni - 0x10000) / 0x400 + 0xD800; - $lo = ($uni - 0x10000) % 0x400 + 0xDC00; + $hi = ($uni - 0x10000) / 0x400 + 0xD800; + $lo = ($uni - 0x10000) % 0x400 + 0xDC00; and the decoding is - $uni = 0x10000 + ($hi - 0xD800) * 0x400 + ($lo - 0xDC00); - -If you try to generate surrogates (for example by using chr()), you -will get a warning, if warnings are turned on, because those code -points are not valid for a Unicode character. + $uni = 0x10000 + ($hi - 0xD800) * 0x400 + ($lo - 0xDC00); Because of the 16-bitness, UTF-16 is byte-order dependent. UTF-16 itself can be used for in-memory computations, but if storage or @@ -1138,12 +1285,23 @@ you will read the bytes C<0xFF 0xFE>. (And if the originating platform was writing in UTF-8, you will read the bytes C<0xEF 0xBB 0xBF>.) The way this trick works is that the character with the code point -C<U+FFFE> is guaranteed not to be a valid Unicode character, so the +C<U+FFFE> is not supposed to be in input streams, so the sequence of bytes C<0xFF 0xFE> is unambiguously "BOM, represented in little-endian format" and cannot be C<U+FFFE>, represented in big-endian -format". (Actually, C<U+FFFE> is legal for use by your program, even for -input/output, but better not use it if you need a BOM. But it is "illegal for -interchange", so that an unsuspecting program won't get confused.) +format". + +Surrogates have no meaning in Unicode outside their use in pairs to +represent other code points. However, Perl allows them to be +represented individually internally, for example by saying +C<chr(0xD801)>, so that all code points, not just those valid for open +interchange, are +representable. Unicode does define semantics for them, such as their +General Category is "Cs". But because their use is somewhat dangerous, +Perl will warn (using the warning category "surrogate", which is a +sub-category of "utf8") if an attempt is made +to do things like take the lower case of one, or match +case-insensitively, or to output them. (But don't try this on Perls +before 5.14.) =item * @@ -1151,17 +1309,18 @@ UTF-32, UTF-32BE, UTF-32LE The UTF-32 family is pretty much like the UTF-16 family, expect that the units are 32-bit, and therefore the surrogate scheme is not -needed. The BOM signatures will be C<0x00 0x00 0xFE 0xFF> for BE and -C<0xFF 0xFE 0x00 0x00> for LE. +needed. UTF-32 is a fixed-width encoding. The BOM signatures are +C<0x00 0x00 0xFE 0xFF> for BE and C<0xFF 0xFE 0x00 0x00> for LE. =item * UCS-2, UCS-4 -Encodings defined by the ISO 10646 standard. UCS-2 is a 16-bit +Legacy, fixed-width encodings defined by the ISO 10646 standard. UCS-2 is a 16-bit encoding. Unlike UTF-16, UCS-2 is not extensible beyond C<U+FFFF>, because it does not use surrogates. UCS-4 is a 32-bit encoding, -functionally identical to UTF-32. +functionally identical to UTF-32 (the difference being that +UCS-4 forbids neither surrogates nor code points larger than 0x10_FFFF). =item * @@ -1172,6 +1331,36 @@ transport or storage is not eight-bit safe. Defined by RFC 2152. =back +=head2 Non-character code points + +66 code points are set aside in Unicode as "non-character code points". +These all have the Unassigned (Cn) General Category, and they never will +be assigned. These are never supposed to be in legal Unicode input +streams, so that code can use them as sentinels that can be mixed in +with character data, and they always will be distinguishable from that data. +To keep them out of Perl input streams, strict UTF-8 should be +specified, such as by using the layer C<:encoding('UTF-8')>. The +non-character code points are the 32 between U+FDD0 and U+FDEF, and the +34 code points U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, ... U+10FFFE, U+10FFFF. +Some people are under the mistaken impression that these are "illegal", +but that is not true. An application or cooperating set of applications +can legally use them at will internally; but these code points are +"illegal for open interchange". Therefore, Perl will not accept these +from input streams unless lax rules are being used, and will warn +(using the warning category "nonchar", which is a sub-category of "utf8") if +an attempt is made to output them. + +=head2 Beyond Unicode code points + +The maximum Unicode code point is U+10FFFF. But Perl accepts code +points up to the maximum permissible unsigned number available on the +platform. However, Perl will not accept these from input streams unless +lax rules are being used, and will warn (using the warning category +"non_unicode", which is a sub-category of "utf8") if an attempt is made to +operate on or output them. For example, C<uc(0x11_0000)> will generate +this warning, returning the input parameter as its result, as the upper +case of every non-Unicode code point is the code point itself. + =head2 Security Implications of Unicode Read L<Unicode Security Considerations|http://www.unicode.org/reports/tr36>. @@ -1183,7 +1372,7 @@ Also, note the following: Malformed UTF-8 -Unfortunately, the specification of UTF-8 leaves some room for +Unfortunately, the original specification of UTF-8 leaves some room for interpretation of how many bytes of encoded output one should generate from one input Unicode character. Strictly speaking, the shortest possible sequence of UTF-8 bytes should be generated, @@ -1191,27 +1380,16 @@ because otherwise there is potential for an input buffer overflow at the receiving end of a UTF-8 connection. Perl always generates the shortest length UTF-8, and with warnings on, Perl will warn about non-shortest length UTF-8 along with other malformations, such as the -surrogates, which are not real Unicode code points. +surrogates, which are not Unicode code points valid for interchange. =item * -Regular expressions behave slightly differently between byte data and -character (Unicode) data. For example, the "word character" character -class C<\w> will work differently depending on if data is eight-bit bytes -or Unicode. - -In the first case, the set of C<\w> characters is either small--the -default set of alphabetic characters, digits, and the "_"--or, if you -are using a locale (see L<perllocale>), the C<\w> might contain a few -more letters according to your language and country. +Regular expression pattern matching may surprise you if you're not +accustomed to Unicode. Starting in Perl 5.14, several pattern +modifiers are available to control this, called the character set +modifiers. Details are given in L<perlre/Character set modifiers>. -In the second case, the C<\w> set of characters is much, much larger. -Most importantly, even in the set of the first 256 characters, it will -probably match different characters: unlike most locales, which are -specific to a language and country pair, Unicode classifies all the -characters that are letters I<somewhere> as C<\w>. For example, your -locale might not think that LATIN SMALL LETTER ETH is a letter (unless -you happen to speak Icelandic), but Unicode does. +=back As discussed elsewhere, Perl has one foot (two hooves?) planted in each of two worlds: the old world of bytes and the new world of @@ -1220,10 +1398,8 @@ If your legacy code does not explicitly use Unicode, no automatic switch-over to characters should happen. Characters shouldn't get downgraded to bytes, either. It is possible to accidentally mix bytes and characters, however (see L<perluniintro>), in which case C<\w> in -regular expressions might start behaving differently. Review your -code. Use warnings and the C<strict> pragma. - -=back +regular expressions might start behaving differently (unless the C</a> +modifier is in effect). Review your code. Use warnings and the C<strict> pragma. =head2 Unicode in Perl on EBCDIC @@ -1238,45 +1414,27 @@ for more discussion of the issues. =head2 Locales -Usually locale settings and Unicode do not affect each other, but -there are a couple of exceptions: - -=over 4 - -=item * - -You can enable automatic UTF-8-ification of your standard file -handles, default C<open()> layer, and C<@ARGV> by using either -the C<-C> command line switch or the C<PERL_UNICODE> environment -variable, see L<perlrun> for the documentation of the C<-C> switch. - -=item * - -Perl tries really hard to work both with Unicode and the old -byte-oriented world. Most often this is nice, but sometimes Perl's -straddling of the proverbial fence causes problems. - -=back +See L<perllocale/Unicode and UTF-8> =head2 When Unicode Does Not Happen While Perl does have extensive ways to input and output in Unicode, -and few other 'entry points' like the @ARGV which can be interpreted -as Unicode (UTF-8), there still are many places where Unicode (in some -encoding or another) could be given as arguments or received as +and a few other "entry points" like the @ARGV array (which can sometimes be +interpreted as UTF-8), there are still many places where Unicode +(in some encoding or another) could be given as arguments or received as results, or both, but it is not. The following are such interfaces. Also, see L</The "Unicode Bug">. For all of these interfaces Perl currently (as of 5.8.3) simply assumes byte strings both as arguments -and results, or UTF-8 strings if the C<encoding> pragma has been used. +and results, or UTF-8 strings if the (problematic) C<encoding> pragma has been used. -One reason why Perl does not attempt to resolve the role of Unicode in -these cases is that the answers are highly dependent on the operating +One reason that Perl does not attempt to resolve the role of Unicode in +these situations is that the answers are highly dependent on the operating system and the file system(s). For example, whether filenames can be -in Unicode, and in exactly what kind of encoding, is not exactly a -portable concept. Similarly for the qx and system: how well will the -'command line interface' (and which of them?) handle Unicode? +in Unicode and in exactly what kind of encoding, is not exactly a +portable concept. Similarly for C<qx> and C<system>: how well will the +"command-line interface" (and which of them?) handle Unicode? =over 4 @@ -1309,11 +1467,15 @@ readdir, readlink =head2 The "Unicode Bug" -The term, the "Unicode bug" has been applied to an inconsistency with the -Unicode characters whose ordinals are in the Latin-1 Supplement block, that +The term, the "Unicode bug" has been applied to an inconsistency +on ASCII platforms with the +Unicode code points in the Latin-1 Supplement block, that is, between 128 and 255. Without a locale specified, unlike all other characters or code points, these characters have very different semantics in -byte semantics versus character semantics. +byte semantics versus character semantics, unless +C<use feature 'unicode_strings'> is specified. +(The lesson here is to specify C<unicode_strings> to avoid the +headaches.) In character semantics they are interpreted as Unicode code points, which means they have the same semantics as Latin-1 (ISO-8859-1). @@ -1321,9 +1483,7 @@ they have the same semantics as Latin-1 (ISO-8859-1). In byte semantics, they are considered to be unassigned characters, meaning that the only semantics they have is their ordinal numbers, and that they are not members of various character classes. None are considered to match C<\w> -for example, but all match C<\W>. (On EBCDIC platforms, the behavior may -be different from this, depending on the underlying C language library -functions.) +for example, but all match C<\W>. The behavior is known to have effects on these areas: @@ -1341,7 +1501,15 @@ Using caseless (C</i>) regular expression matching =item * -Matching a number of properties in regular expressions, such as C<\w> +Matching any of several properties in regular expressions, namely C<\b>, +C<\B>, C<\s>, C<\S>, C<\w>, C<\W>, and all the Posix character classes +I<except> C<[[:ascii:]]>. + +=item * + +In C<quotemeta> or its inline equivalent C<\Q>, no characters +code points above 127 are quoted in UTF-8 encoded strings, but in +byte encoded strings, code points between 128-255 are always quoted. =item * @@ -1357,6 +1525,7 @@ which changes the string's semantics from byte to character or vice versa. As an example, consider the following program and its output: $ perl -le' + no feature 'unicode_strings'; $s1 = "\xC2"; $s2 = "\x{2660}"; for ($s1, $s2, $s1.$s2) { @@ -1375,22 +1544,24 @@ ASCII range (except in a locale), along with Perl's desire to add Unicode support seamlessly. The result wasn't seamless: these characters were orphaned. -Work is being done to correct this, but only some of it was complete in time -for the 5.12 release. What has been finished is the important part of the case -changing component. Due to concerns, and some evidence, that older code might -have come to rely on the existing behavior, the new behavior must be explicitly -enabled by the feature C<unicode_strings> in the L<feature> pragma, even though -no new syntax is involved. - -See L<perlfunc/lc> for details on how this pragma works in combination with -various others for casing. Even though the pragma only affects casing -operations in the 5.12 release, it is planned to have it affect all the -problematic behaviors in later releases: you can't have one without them all. - -In the meantime, a workaround is to always call utf8::upgrade($string), or to -use the standard module L<Encode>. Also, a scalar that has any characters +Starting in Perl 5.14, C<use feature 'unicode_strings'> can be used to +cause Perl to use Unicode semantics on all string operations within the +scope of the feature subpragma. Regular expressions compiled in its +scope retain that behavior even when executed or compiled into larger +regular expressions outside the scope. (The pragma does not, however, +affect the C<quotemeta> behavior. Nor does it affect the deprecated +user-defined case changing operations--these still require a UTF-8 +encoded string to operate.) + +In Perl 5.12, the subpragma affected casing changes, but not regular +expressions. See L<perlfunc/lc> for details on how this pragma works in +combination with various others for casing. + +For earlier Perls, or when a string is passed to a function outside the +subpragma's scope, a workaround is to always call C<utf8::upgrade($string)>, +or to use the standard module L<Encode>. Also, a scalar that has any characters whose ordinal is above 0x100, or which were specified using either of the -C<\N{...}> notations will automatically have character semantics. +C<\N{...}> notations, will automatically have character semantics. =head2 Forcing Unicode in Perl (Or Unforcing Unicode in Perl) @@ -1503,9 +1674,10 @@ output more readable. =item * -C<ibcmp_utf8(s1, pe1, l1, u1, s2, pe2, l2, u2)> can be used to +C<foldEQ_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. +comparisons you can just use C<memEQ()> and C<memNE()> as usual, except +if one string is in utf8 and the other isn't. =back @@ -1517,16 +1689,16 @@ in the Perl source code distribution. Perl by default comes with the latest supported Unicode version built in, but you can change to use any earlier one. -Download the files in the version of Unicode that you want from the Unicode web +Download the files in the desired version of Unicode from the Unicode web site L<http://www.unicode.org>). These should replace the existing files in -C<\$Config{privlib}>/F<unicore>. (C<\%Config> is available from the Config -module.) Follow the instructions in F<README.perl> in that directory to change -some of their names, and then run F<make>. - -It is even possible to download them to a different directory, and then change -F<utf8_heavy.pl> in the directory C<\$Config{privlib}> to point to the new -directory, or maybe make a copy of that directory before making the change, and -using C<@INC> or the C<-I> run-time flag to switch between versions at will +F<lib/unicore> in the Perl source tree. Follow the instructions in +F<README.perl> in that directory to change some of their names, and then build +perl (see F<INSTALL>). + +It is even possible to copy the built files to a different directory, and then +change F<utf8_heavy.pl> in the directory C<$Config{privlib}> to point to the +new directory, or maybe make a copy of that directory before making the change, +and using C<@INC> or the C<-I> run-time flag to switch between versions at will (but because of caching, not in the middle of a process), but all this is beyond the scope of these instructions. @@ -1534,30 +1706,17 @@ beyond the scope of these instructions. =head2 Interaction with Locales -Use of locales with Unicode data may lead to odd results. Currently, -Perl attempts to attach 8-bit locale info to characters in the range -0..255, but this technique is demonstrably incorrect for locales that -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. +See L<perllocale/Unicode and UTF-8> =head2 Problems with characters in the Latin-1 Supplement range See L</The "Unicode Bug"> -=head2 Problems with case-insensitive regular expression matching - -There are problems with case-insensitive matches, including those involving -character classes (enclosed in [square brackets]), characters whose fold -is to multiple characters (such as the single character LATIN SMALL LIGATURE -FFL matches case-insensitively with the 3-character string C<ffl>), and -characters in the Latin-1 Supplement. - =head2 Interaction with Extensions When Perl exchanges data with an extension, the extension should be able to understand the UTF8 flag and act accordingly. If the -extension doesn't know about the flag, it's likely that the extension +extension doesn't recognize that flag, it's likely that the extension will return incorrectly-flagged data. So if you're working with Unicode data, consult the documentation of @@ -1581,13 +1740,14 @@ would convert the argument to raw UTF-8 and convert the result back to Perl's internal representation like so: sub my_escape_html ($) { - my($what) = shift; - return unless defined $what; - Encode::decode_utf8(Foo::Bar::escape_html(Encode::encode_utf8($what))); + my($what) = shift; + return unless defined $what; + Encode::decode_utf8(Foo::Bar::escape_html( + Encode::encode_utf8($what))); } Sometimes, when the extension does not convert data but just stores -and retrieves them, you will be in a position to use the otherwise +and retrieves them, you will be able to use the otherwise dangerous Encode::_utf8_on() function. Let's say the popular C<Foo::Bar> extension, written in C, provides a C<param> method that lets you store and retrieve data according to these prototypes: @@ -1630,12 +1790,12 @@ somewhat less spectacular, at least for some operations. In general, operations with UTF-8 encoded strings are still slower. As an example, the Unicode properties (character classes) like C<\p{Nd}> are known to be quite a bit slower (5-20 times) than their simpler counterparts -like C<\d> (then again, there 268 Unicode characters matching C<Nd> +like C<\d> (then again, there are hundreds of Unicode characters matching C<Nd> compared with the 10 ASCII characters matching C<d>). =head2 Problems on EBCDIC platforms -There are a number of known problems with Perl on EBCDIC platforms. If you +There are several known problems with Perl on EBCDIC platforms. If you want to use Perl there, send email to perlbug@perl.org. In earlier versions, when byte and character data were concatenated, @@ -1714,7 +1874,8 @@ to deal with UTF-8 data. Please check the documentation to verify if that is still true. sub fetchrow { - my($self, $sth, $what) = @_; # $what is one of fetchrow_{array,hashref} + # $what is one of fetchrow_{array,hashref} + my($self, $sth, $what) = @_; if ($] < 5.007) { return $sth->$what; } else { @@ -1729,7 +1890,9 @@ that is still true. my $ret = $sth->$what; if (ref $ret) { for my $k (keys %$ret) { - defined && /[^\000-\177]/ && Encode::_utf8_on($_) for $ret->{$k}; + defined + && /[^\000-\177]/ + && Encode::_utf8_on($_) for $ret->{$k}; } return $ret; } else { diff --git a/Master/tlpkg/tlperl/lib/pods/perlunifaq.pod b/Master/tlpkg/tlperl/lib/pods/perlunifaq.pod index ab42ff194a0..9fd2b380567 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlunifaq.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlunifaq.pod @@ -84,12 +84,12 @@ or encode anymore, on things that use the layered handle. You can provide this layer when C<open>ing the file: - open my $fh, '>:encoding(UTF-8)', $filename; # auto encoding on write - open my $fh, '<:encoding(UTF-8)', $filename; # auto decoding on read + open my $fh, '>:encoding(UTF-8)', $filename; # auto encoding on write + open my $fh, '<:encoding(UTF-8)', $filename; # auto decoding on read Or if you already have an open filehandle: - binmode $fh, ':encoding(UTF-8)'; + binmode $fh, ':encoding(UTF-8)'; Some database drivers for DBI can also automatically encode and decode, but that is sometimes limited to the UTF-8 encoding. @@ -138,28 +138,27 @@ concern, and you can just C<eval> dumped data as always. =head2 Why do some characters not uppercase or lowercase correctly? -It seemed like a good idea at the time, to keep the semantics the same for -standard strings, when Perl got Unicode support. The plan is to fix this -in the future, and the casing component has in fact mostly been fixed, but we -have to deal with the fact that Perl treats equal strings differently, -depending on the internal state. - -First the casing. Just put a C<use feature 'unicode_strings'> near the -beginning of your program. Within its lexical scope, C<uc>, C<lc>, C<ucfirst>, -C<lcfirst>, and the regular expression escapes C<\U>, C<\L>, C<\u>, C<\l> use -Unicode semantics for changing case regardless of whether the UTF8 flag is on -or not. However, if you pass strings to subroutines in modules outside the -pragma's scope, they currently likely won't behave this way, and you have to -try one of the solutions below. There is another exception as well: if you -have furnished your own casing functions to override the default, these will -not be called unless the UTF8 flag is on) - -This remains a problem for the regular expression constructs -C<\d>, C<\s>, C<\w>, C<\D>, C<\S>, C<\W>, C</.../i>, C<(?i:...)>, -and C</[[:posix:]]/>. - -To force Unicode semantics, you can upgrade the internal representation to -by doing C<utf8::upgrade($string)>. This can be used +Starting in Perl 5.14 (and partially in Perl 5.12), just put a +C<use feature 'unicode_strings'> near the beginning of your program. +Within its lexical scope you shouldn't have this problem. It also is +automatically enabled under C<use feature ':5.12'> or using C<-E> on the +command line for Perl 5.12 or higher. + +The rationale for requiring this is to not break older programs that +rely on the way things worked before Unicode came along. Those older +programs knew only about the ASCII character set, and so may not work +properly for additional characters. When a string is encoded in UTF-8, +Perl assumes that the program is prepared to deal with Unicode, but when +the string isn't, Perl assumes that only ASCII (unless it is an EBCDIC +platform) is wanted, and so those characters that are not ASCII +characters aren't recognized as to what they would be in Unicode. +C<use feature 'unicode_strings'> tells Perl to treat all characters as +Unicode, whether the string is encoded in UTF-8 or not, thus avoiding +the problem. + +However, on earlier Perls, or if you pass strings to subroutines outside +the feature's scope, you can force Unicode semantics by changing the +encoding to UTF-8 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. diff --git a/Master/tlpkg/tlperl/lib/pods/perluniintro.pod b/Master/tlpkg/tlperl/lib/pods/perluniintro.pod index bee286f5eaa..3fbff0024fd 100644 --- a/Master/tlpkg/tlperl/lib/pods/perluniintro.pod +++ b/Master/tlpkg/tlperl/lib/pods/perluniintro.pod @@ -5,21 +5,22 @@ perluniintro - Perl Unicode introduction =head1 DESCRIPTION This document gives a general idea of Unicode and how to use Unicode -in Perl. +in Perl. See L</Further Resources> for references to more in-depth +treatments of Unicode. =head2 Unicode Unicode is a character set standard which plans to codify all of the writing systems of the world, plus many other symbols. -Unicode and ISO/IEC 10646 are coordinated standards that provide code -points for characters in almost all modern character set standards, -covering more than 30 writing systems and hundreds of languages, +Unicode and ISO/IEC 10646 are coordinated standards that unify +almost all other modern character set standards, +covering more than 80 writing systems and hundreds of languages, including all commercially-important modern languages. All characters in the largest Chinese, Japanese, and Korean dictionaries are also encoded. The standards will eventually cover almost all characters in more than 250 writing systems and thousands of languages. -Unicode 1.0 was released in October 1991, and 4.0 in April 2003. +Unicode 1.0 was released in October 1991, and 6.0 in October 2010. 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>. @@ -31,7 +32,9 @@ those characters. Unicode defines characters like C<LATIN CAPITAL LETTER A> or C<GREEK SMALL LETTER ALPHA> and unique numbers for the characters, in this case 0x0041 and 0x03B1, respectively. These unique numbers are called -I<code points>. +I<code points>. A code point is essentially the position of the +character within the set of all possible Unicode characters, and thus in +Perl, the term I<ordinal> is often used interchangeably with it. The Unicode standard prefers using hexadecimal notation for the code points. If numbers like C<0x0041> are unfamiliar to you, take a peek @@ -51,39 +54,41 @@ modelled by a I<base character> (like C<LATIN CAPITAL LETTER A>) followed by one or more I<modifiers> (like C<COMBINING ACUTE ACCENT>). This sequence of base character and modifiers is called a I<combining character sequence>. Some non-western languages require more complicated -models, so Unicode created the I<grapheme cluster> concept, and then the -I<extended grapheme cluster>. For example, a Korean Hangul syllable is -considered a single logical character, but most often consists of three actual +models, so Unicode created the I<grapheme cluster> concept, which was +later further refined into the I<extended grapheme cluster>. For +example, a Korean Hangul syllable is considered a single logical +character, but most often consists of three actual Unicode characters: a leading consonant followed by an interior vowel followed by a trailing consonant. Whether to call these extended grapheme clusters "characters" depends on your point of view. If you are a programmer, you probably would tend towards seeing -each element in the sequences as one unit, or "character". The whole sequence -could be seen as one "character", however, from the user's point of view, since -that's probably what it looks like in the context of the user's language. - -With this "whole sequence" view of characters, the total number of -characters is open-ended. But in the programmer's "one unit is one -character" point of view, the concept of "characters" is more -deterministic. In this document, we take that second point of view: -one "character" is one Unicode code point. - -For some combinations, there are I<precomposed> characters. -C<LATIN CAPITAL LETTER A WITH ACUTE>, for example, is defined as -a single code point. These precomposed characters are, however, -only available for some combinations, and are mainly -meant to support round-trip conversions between Unicode and legacy -standards (like the ISO 8859). In the general case, the composing -method is more extensible. To support conversion between -different compositions of the characters, various I<normalization -forms> to standardize representations are also defined. +each element in the sequences as one unit, or "character". However from +the user's point of view, the whole sequence could be seen as one +"character" since that's probably what it looks like in the context of the +user's language. In this document, we take the programmer's point of +view: one "character" is one Unicode code point. + +For some combinations of base character and modifiers, there are +I<precomposed> characters. There is a single character equivalent, for +example, to the sequence C<LATIN CAPITAL LETTER A> followed by +C<COMBINING ACUTE ACCENT>. It is called C<LATIN CAPITAL LETTER A WITH +ACUTE>. These precomposed characters are, however, only available for +some combinations, and are mainly meant to support round-trip +conversions between Unicode and legacy standards (like ISO 8859). Using +sequences, as Unicode does, allows for needing fewer basic building blocks +(code points) to express many more potential grapheme clusters. To +support conversion between equivalent forms, various I<normalization +forms> are also defined. Thus, C<LATIN CAPITAL LETTER A WITH ACUTE> is +in I<Normalization Form Composed>, (abbreviated NFC), and the sequence +C<LATIN CAPITAL LETTER A> followed by C<COMBINING ACUTE ACCENT> +represents the same character in I<Normalization Form Decomposed> (NFD). Because of backward compatibility with legacy encodings, the "a unique number for every character" idea breaks down a bit: instead, there is "at least one number for every character". The same character could be represented differently in several legacy encodings. The -converse is also not true: some code points do not have an assigned +converse is not also true: some code points do not have an assigned character. Firstly, there are unallocated code points within otherwise used blocks. Secondly, there are special Unicode control characters that do not represent true characters. @@ -128,24 +133,36 @@ natively. Perl 5.8.0, however, is the first recommended release for serious Unicode work. The maintenance release 5.6.1 fixed many of the problems of the initial Unicode implementation, but for example regular expressions still do not work with Unicode in 5.6.1. - -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 +Perl 5.14.0 is the first release where Unicode support is +(almost) seamlessly integrable without some gotchas (the exception being +some differences in L<quotemeta|perlfunc/quotemeta>). To enable this +seamless support, you should C<use feature 'unicode_strings'> (which is +automatically selected if you C<use 5.012> or higher). See L<feature>. +(5.14 also fixes a number of bugs and departures from the Unicode +standard.) + +Before Perl 5.8.0, the use of C<use utf8> was used to declare that operations in the current block or file would be Unicode-aware. This model was found to be wrong, or at least clumsy: the "Unicodeness" is now carried with the data, instead of being attached to the -operations. Only one case remains where an explicit C<use utf8> is -needed: if your Perl script itself is encoded in UTF-8, you can use -UTF-8 in your identifier names, and in string and regular expression +operations. +Starting with Perl 5.8.0, only one case remains where an explicit C<use +utf8> is needed: if your Perl script itself is encoded in UTF-8, you can +use UTF-8 in your identifier names, and in string and regular expression literals, by saying C<use utf8>. This is not the default because scripts with legacy 8-bit data in them would break. See L<utf8>. =head2 Perl's Unicode Model Perl supports both pre-5.6 strings of eight-bit native bytes, and -strings of Unicode characters. The principle is that Perl tries to -keep its data as eight-bit bytes for as long as possible, but as soon -as Unicodeness cannot be avoided, the data is (mostly) transparently upgraded -to Unicode. There are some problems--see L<perlunicode/The "Unicode Bug">. +strings of Unicode characters. The general principle is that Perl tries +to keep its data as eight-bit bytes for as long as possible, but as soon +as Unicodeness cannot be avoided, the data is transparently upgraded +to Unicode. Prior to Perl 5.14, the upgrade was not completely +transparent (see L<perlunicode/The "Unicode Bug">), and for backwards +compatibility, full transparency is not gained unless C<use feature +'unicode_strings'> (see L<feature>) or C<use 5.012> (or higher) is +selected. Internally, Perl currently uses either whatever the native eight-bit character set of the platform (for example Latin-1) is, defaulting to @@ -182,10 +199,11 @@ handles, default C<open()> layer, and C<@ARGV> by using either the C<-C> command line switch or the C<PERL_UNICODE> environment variable, see L<perlrun> for the documentation of the C<-C> switch. -Note that this means that Perl expects other software to work, too: +Note that this means that Perl expects other software to work the same +way: if Perl has been led to believe that STDIN should be UTF-8, but then -STDIN coming in from another command is not UTF-8, Perl will complain -about the malformed UTF-8. +STDIN coming in from another command is not UTF-8, Perl will likely +complain about the malformed UTF-8. All features that combine Unicode and I/O also require using the new PerlIO feature. Almost all Perl 5.8 platforms do use PerlIO, though: @@ -248,7 +266,7 @@ characters: Note that both C<\x{...}> and C<\N{...}> are compile-time string constants: you cannot use variables in them. if you want similar -run-time functionality, use C<chr()> and C<charnames::vianame()>. +run-time functionality, use C<chr()> and C<charnames::string_vianame()>. If you want to force the result to Unicode characters, use the special C<"U0"> prefix. It consumes no arguments but causes the following bytes @@ -273,16 +291,18 @@ example print length("\N{LATIN CAPITAL LETTER A}\N{COMBINING ACUTE ACCENT}"), "\n"; will print 2, not 1. The only exception is that regular expressions -have C<\X> for matching an extended grapheme cluster. +have C<\X> for matching an extended grapheme cluster. (Thus C<\X> in a +regular expression would match the entire sequence of both the example +characters.) Life is not quite so transparent, however, when working with legacy encodings, I/O, and certain special cases: =head2 Legacy Encodings -When you combine legacy data and Unicode the legacy data needs -to be upgraded to Unicode. Normally ISO 8859-1 (or EBCDIC, if -applicable) is assumed. +When you combine legacy data and Unicode, the legacy data needs +to be upgraded to Unicode. Normally the legacy data is assumed to be +ISO 8859-1 (or EBCDIC, if applicable). The C<Encode> module knows about many encodings and has interfaces for doing conversions between those encodings: @@ -321,9 +341,10 @@ and on already open streams, use C<binmode()>: The matching of encoding names is loose: case does not matter, and many encodings have several aliases. Note that the C<:utf8> layer must always be specified exactly like that; it is I<not> subject to -the loose matching of encoding names. Also note that C<:utf8> is unsafe for +the loose matching of encoding names. Also note that currently C<:utf8> is unsafe for input, because it accepts the data without validating that it is indeed valid -UTF8. +UTF-8; you should instead use C<:encoding(utf-8)> (with or without a +hyphen). See L<PerlIO> for the C<:utf8> layer, L<PerlIO::encoding> and L<Encode::PerlIO> for the C<:encoding()> layer, and @@ -344,7 +365,8 @@ layer when opening files The I/O layers can also be specified more flexibly with the C<open> pragma. See L<open>, or look at the following example. - use open ':encoding(utf8)'; # input/output default encoding will be UTF-8 + use open ':encoding(utf8)'; # input/output default encoding will be + # UTF-8 open X, ">file"; print X chr(0x100), "\n"; close X; @@ -355,7 +377,8 @@ the C<open> pragma. See L<open>, or look at the following example. With the C<open> pragma you can use the C<:locale> layer BEGIN { $ENV{LC_ALL} = $ENV{LANG} = 'ru_RU.KOI8-R' } - # the :locale will probe the locale environment variables like LC_ALL + # the :locale will probe the locale environment variables like + # LC_ALL use open OUT => ':locale'; # russki parusski open(O, ">koi8"); print O chr(0x430); # Unicode CYRILLIC SMALL LETTER A = KOI8-R 0xc1 @@ -432,13 +455,13 @@ its argument so that Unicode characters with code points greater than 255 are displayed as C<\x{...}>, control characters (like C<\n>) are displayed as C<\x..>, and the rest of the characters as themselves: - sub nice_string { - join("", - map { $_ > 255 ? # if wide character... - sprintf("\\x{%04X}", $_) : # \x{...} - chr($_) =~ /[[:cntrl:]]/ ? # else if control character ... - sprintf("\\x%02X", $_) : # \x.. - quotemeta(chr($_)) # else quoted or as themselves + sub nice_string { + join("", + map { $_ > 255 ? # if wide character... + sprintf("\\x{%04X}", $_) : # \x{...} + chr($_) =~ /[[:cntrl:]]/ ? # else if control character ... + sprintf("\\x%02X", $_) : # \x.. + quotemeta(chr($_)) # else quoted or as themselves } unpack("W*", $_[0])); # unpack Unicode characters } @@ -513,7 +536,7 @@ C<LATIN CAPITAL LETTER A>?) The short answer is that by default Perl compares equivalence (C<eq>, C<ne>) based only on code points of the characters. In the above case, the answer is no (because 0x00C1 != 0x0041). But sometimes, any -CAPITAL LETTER As should be considered equal, or even As of any case. +CAPITAL LETTER A's should be considered equal, or even A's of any case. The long answer is that you need to consider character normalization and casing issues: see L<Unicode::Normalize>, Unicode Technical Report #15, @@ -521,7 +544,8 @@ L<Unicode Normalization Forms|http://www.unicode.org/unicode/reports/tr15> and sections on case mapping in the L<Unicode Standard|http://www.unicode.org>. As of Perl 5.8.0, the "Full" case-folding of I<Case -Mappings/SpecialCasing> is implemented, but bugs remain in C<qr//i> with them. +Mappings/SpecialCasing> is implemented, but bugs remain in C<qr//i> with them, +mostly fixed by 5.14. =item * @@ -575,6 +599,8 @@ Unicode does define several other decimal--and numeric--characters besides the familiar 0 to 9, such as the Arabic and Indic digits. Perl does not support string-to-number conversion for digits other than ASCII 0 to 9 (and ASCII a to f for hexadecimal). +To get safe conversions from any Unicode string, use +L<Unicode::UCD/num()>. =back @@ -601,13 +627,18 @@ How Do I Make My Scripts Work With Unicode? Very little work should be needed since nothing changes until you generate Unicode data. The most important thing is getting input as Unicode; for that, see the earlier I/O discussion. +To get full seamless Unicode support, add +C<use feature 'unicode_strings'> (or C<use 5.012> or higher) to your +script. =item * How Do I Know Whether My String Is In Unicode? -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 are different depending on +You shouldn't have to care. But you may if your Perl is before 5.14.0 +or you haven't specified C<use feature 'unicode_strings'> or C<use +5.012> (or higher) because otherwise the semantics of the code points +in the range 128 to 255 are different depending on whether the string they are contained within is in Unicode or not. (See L<perlunicode/When Unicode Does Not Happen>.) @@ -625,7 +656,7 @@ as a single byte encoding. If the flag is on, the bytes in the scalar are interpreted as the (variable-length, potentially multi-byte) UTF-8 encoded code points of the characters. Bytes added to a UTF-8 encoded string are automatically upgraded to UTF-8. If mixed non-UTF-8 and UTF-8 scalars -are merged (double-quoted interpolation, explicit concatenation, and +are merged (double-quoted interpolation, explicit concatenation, or printf/sprintf parameter substitution), the result will be UTF-8 encoded as if copies of the byte strings were upgraded to UTF-8: for example, @@ -638,8 +669,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 -the C<length()> function: +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 @@ -652,6 +683,12 @@ the C<length()> function: =item * +How Do I Find Out What Encoding a File Has? + +You might try L<Encode::Guess>, but it has a number of limitations. + +=item * + How Do I Detect Data That's Not Valid In a Particular Encoding? Use the C<Encode> package to try converting it. @@ -731,11 +768,11 @@ or: You can find the bytes that make up a UTF-8 sequence with - @bytes = unpack("C*", $Unicode_string) + @bytes = unpack("C*", $Unicode_string) and you can create well-formed Unicode with - $Unicode_string = pack("U*", 0xff, ...) + $Unicode_string = pack("U*", 0xff, ...) =item * @@ -748,8 +785,14 @@ L<http://www.cl.cam.ac.uk/~mgk25/unicode.html> How Does Unicode Work With Traditional Locales? -In Perl, not very well. Avoid using locales through the C<locale> -pragma. Use only one or the other. But see L<perlrun> for the +Perl tries to keep the two separated. Code points that are above 255 +are treated as Unicode; those below 256, generally as locale. This +works reasonably well except in some case-insensitive regular expression +pattern matches that in Unicode would cross the 255/256 boundary. These +are disallowed. +Also, the C<\p{}> and C<\N{}> constructs silently assume Unicode values +even for code points below 256. +See also L<perlrun> for the description of the C<-C> switch and its environment counterpart, C<$ENV{PERL_UNICODE}> to see how to enable various Unicode features, for example by using locale settings. @@ -810,6 +853,14 @@ L<http://www.unicode.org/glossary/> =item * +Unicode Recommended Reading List + +The Unicode Consortium has a list of articles and books, some of which +give a much more in depth treatment of Unicode: +L<http://unicode.org/resources/readinglist.html> + +=item * + Unicode Useful Resources L<http://www.unicode.org/unicode/onlinedat/resources.html> @@ -835,22 +886,6 @@ L<http://www.eki.ee/letter/> =item * -The Unicode support files live within the Perl installation in the -directory - - $Config{installprivlib}/unicore - -in Perl 5.8.0 or newer, and - - $Config{installprivlib}/unicode - -in the Perl 5.6 series. (The renaming to F<lib/unicore> was done to -avoid naming conflicts with lib/Unicode in case-insensitive filesystems.) -The main Unicode data file is F<UnicodeData.txt> (or F<Unicode.301> in -Perl 5.6.1.) You can find the C<$Config{installprivlib}> by - - perl "-V:installprivlib" - You can explore various information from the Unicode data files using the C<Unicode::UCD> module. @@ -887,6 +922,6 @@ mailing lists for their valuable feedback. =head1 AUTHOR, COPYRIGHT, AND LICENSE -Copyright 2001-2002 Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt> +Copyright 2001-2011 Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt> This document may be distributed under the same terms as Perl itself. diff --git a/Master/tlpkg/tlperl/lib/pods/perluniprops.pod b/Master/tlpkg/tlperl/lib/pods/perluniprops.pod index 4768df20325..2968f5bbda9 100644 --- a/Master/tlpkg/tlperl/lib/pods/perluniprops.pod +++ b/Master/tlpkg/tlperl/lib/pods/perluniprops.pod @@ -2,7 +2,7 @@ # !!!!!!! DO NOT EDIT THIS FILE !!!!!!! # This file is machine-generated by mktables from the Unicode -# database, Version 5.2.0. Any changes made here will be lost! +# database, Version 6.0.0. Any changes made here will be lost! To change this file, edit mktables instead. @@ -11,7 +11,7 @@ To change this file, edit mktables instead. =head1 NAME -perluniprops - Index of Unicode Version 5.2.0 properties in Perl +perluniprops - Index of Unicode Version 6.0.0 properties in Perl =head1 DESCRIPTION @@ -28,7 +28,7 @@ Perl extension. There is some detail about Blocks, Scripts, General_Category, and Bidi_Class in L<perlunicode>, but to find out about the intricacies of the Unicode properties, refer to the Unicode standard. A good starting place is L<http://www.unicode.org/reports/tr44/>. More information on the Perl extensions is in -L<perlrecharclass>. +L<perlunicode/Other Properties>. Note that you can define your own properties; see L<perlunicode/"User-Defined Character Properties">. @@ -42,7 +42,7 @@ both single and compound forms. B<Compound forms> consist of two components, separated by an equals sign or a colon. The first component is the property name, and the second component is the particular value of the property to match against, for example, -'\p{Script: Greek}' or '\p{Script=Greek}' both mean to match characters +'\p{Script: Greek}' and '\p{Script=Greek}' both mean to match characters whose Script property is Greek. B<Single forms>, like '\p{Greek}', are mostly Perl-defined shortcuts for @@ -93,30 +93,29 @@ adjacent to (but within) the braces and the colon or equal sign. =back -Some properties are considered obsolete, but still available. There are -several varieties of obsolesence: +Some properties are considered obsolete by Unicode, but still available. +There are several varieties of obsolescence: =over 4 =item Obsolete Properties marked with an 'B<O>' in the table are considered -obsolete. At the time of this writing (Unicode version 5.2) there is no -information in the Unicode standard about the implications of a property being obsolete. =item Stabilized -Obsolete properties may be stabilized. This means that they are not actively -maintained by Unicode, and will not be extended as new characters are added to -the standard. Such properties are marked with an 'B<S>' in the -table. At the time of this writing (Unicode version 5.2) there is no further -information in the Unicode standard about the implications of a property being -stabilized. +Obsolete properties may be stabilized. Such a determination does not indicate +that the property should or should not be used; instead it is a declaration +that the property will not be maintained nor extended for newly encoded +characters. Such properties are marked with an 'B<S>' in the +table. =item Deprecated -Obsolete properties may be deprecated. This means that their use is strongly +An obsolete property may be deprecated, perhaps because its original intent +has been replaced by another property, or because its specification was +somehow defective. This means that its use is strongly discouraged, so much so that a warning will be issued if used, unless the regular expression is in the scope of a C<S<no warnings 'deprecated'>> statement. A 'B<D>' flags each such entry in the table, and @@ -150,7 +149,7 @@ avoid this, or even more clearly, use the compound form, e.g., The table below has two columns. The left column contains the \p{} -constructs to look up, possibly preceeded by the flags mentioned above; and +constructs to look up, possibly preceded by the flags mentioned above; and the right column contains information about them, like a description, or synonyms. It shows both the single and compound forms for each property that has them. If the left column is a short name for a property, the right column @@ -168,6 +167,15 @@ Numbers in (parentheses) indicate the total number of code points matched by the property. For emphasis, those properties that match no code points at all are listed as well in a separate section following the table. +Most properties match the same code points regardless of whether C<"/i"> +case-insensitive matching is specified or not. But a few properties are +affected. These are shown with the notation + + (/i= other_property) + +in the second column. Under case-insensitive matching they match the +same code pode points as the property "other_property". + There is no description given for most non-Perl defined properties (See http://www.unicode.org/reports/tr44/ for that). @@ -254,19 +262,23 @@ this property. T \p{Age: 5.2} Code point's usage was introduced in version 5.2; See also Property 'Present_In' (6648) + T \p{Age: 6.0} Code point's usage was introduced in + version 6.0; See also Property + 'Present_In' (2088) \p{Age: Unassigned} Code point's usage has not been assigned in any Unicode release thus far. - (867_169) + (865_081) \p{AHex} \p{ASCII_Hex_Digit} (= \p{ASCII_Hex_Digit= Y}) (22) \p{AHex: *} \p{ASCII_Hex_Digit: *} + X \p{Alchemical_Symbols} \p{Block=Alchemical_Symbols} (128) \p{All} \p{Any} (1_114_112) - \p{Alnum} Alphabetic and (Decimal) Numeric (100_931) - \p{Alpha} \p{Alphabetic=Y} (100_520) + \p{Alnum} Alphabetic and (Decimal) Numeric (101_959) + \p{Alpha} \p{Alphabetic=Y} (101_539) \p{Alpha: *} \p{Alphabetic: *} - \p{Alphabetic} \p{Alpha} (= \p{Alphabetic=Y}) (100_520) - \p{Alphabetic: N*} (Short: \p{Alpha=N}, \P{Alpha}) (1_013_592) - \p{Alphabetic: Y*} (Short: \p{Alpha=Y}, \p{Alpha}) (100_520) + \p{Alphabetic} \p{Alpha} (= \p{Alphabetic=Y}) (101_539) + \p{Alphabetic: N*} (Short: \p{Alpha=N}, \P{Alpha}) (1_012_573) + \p{Alphabetic: Y*} (Short: \p{Alpha=Y}, \p{Alpha}) (101_539) X \p{Alphabetic_Presentation_Forms} \p{Block= Alphabetic_Presentation_Forms} (80) X \p{Ancient_Greek_Musical_Notation} \p{Block= @@ -275,9 +287,9 @@ this property. X \p{Ancient_Symbols} \p{Block=Ancient_Symbols} (64) \p{Any} [\x{0000}-\x{10FFFF}] (1_114_112) \p{Arab} \p{Arabic} (= \p{Script=Arabic}) (NOT - \p{Block=Arabic}) (1030) + \p{Block=Arabic}) (1051) \p{Arabic} \p{Script=Arabic} (Short: \p{Arab}; NOT - \p{Block=Arabic}) (1030) + \p{Block=Arabic}) (1051) X \p{Arabic_Presentation_Forms_A} \p{Block= Arabic_Presentation_Forms_A} (688) X \p{Arabic_Presentation_Forms_B} \p{Block= @@ -296,7 +308,7 @@ this property. (22) \p{ASCII_Hex_Digit: N*} (Short: \p{AHex=N}, \P{AHex}) (1_114_090) \p{ASCII_Hex_Digit: Y*} (Short: \p{AHex=Y}, \p{AHex}) (22) - \p{Assigned} All assigned code points (246_877) + \p{Assigned} All assigned code points (248_965) \p{Avestan} \p{Script=Avestan} (Short: \p{Avst}; NOT \p{Block=Avestan}) (61) \p{Avst} \p{Avestan} (= \p{Script=Avestan}) (NOT @@ -306,10 +318,15 @@ this property. \p{Balinese} \p{Script=Balinese} (Short: \p{Bali}; NOT \p{Block=Balinese}) (121) \p{Bamu} \p{Bamum} (= \p{Script=Bamum}) (NOT - \p{Block=Bamum}) (88) + \p{Block=Bamum}) (657) \p{Bamum} \p{Script=Bamum} (Short: \p{Bamu}; NOT - \p{Block=Bamum}) (88) + \p{Block=Bamum}) (657) + X \p{Bamum_Supplement} \p{Block=Bamum_Supplement} (576) X \p{Basic_Latin} \p{ASCII} (= \p{Block=Basic_Latin}) (128) + \p{Batak} \p{Script=Batak} (Short: \p{Batk}; NOT + \p{Block=Batak}) (56) + \p{Batk} \p{Batak} (= \p{Script=Batak}) (NOT + \p{Block=Batak}) (56) \p{Bc: *} \p{Bidi_Class: *} \p{Beng} \p{Bengali} (= \p{Script=Bengali}) (NOT \p{Block=Bengali}) (92) @@ -322,31 +339,31 @@ this property. \p{Bidi_Class: Arabic_Letter} (Short: \p{Bc=AL}) (1116) \p{Bidi_Class: Arabic_Number} (Short: \p{Bc=AN}) (48) \p{Bidi_Class: B} \p{Bidi_Class=Paragraph_Separator} (7) - \p{Bidi_Class: BN} \p{Bidi_Class=Boundary_Neutral} (4016) - \p{Bidi_Class: Boundary_Neutral} (Short: \p{Bc=BN}) (4016) + \p{Bidi_Class: BN} \p{Bidi_Class=Boundary_Neutral} (4015) + \p{Bidi_Class: Boundary_Neutral} (Short: \p{Bc=BN}) (4015) \p{Bidi_Class: Common_Separator} (Short: \p{Bc=CS}) (15) \p{Bidi_Class: CS} \p{Bidi_Class=Common_Separator} (15) \p{Bidi_Class: EN} \p{Bidi_Class=European_Number} (131) \p{Bidi_Class: ES} \p{Bidi_Class=European_Separator} (12) - \p{Bidi_Class: ET} \p{Bidi_Class=European_Terminator} (63) + \p{Bidi_Class: ET} \p{Bidi_Class=European_Terminator} (64) \p{Bidi_Class: European_Number} (Short: \p{Bc=EN}) (131) \p{Bidi_Class: European_Separator} (Short: \p{Bc=ES}) (12) - \p{Bidi_Class: European_Terminator} (Short: \p{Bc=ET}) (63) - \p{Bidi_Class: L} \p{Bidi_Class=Left_To_Right} (1_099_541) - \p{Bidi_Class: Left_To_Right} (Short: \p{Bc=L}) (1_099_541) + \p{Bidi_Class: European_Terminator} (Short: \p{Bc=ET}) (64) + \p{Bidi_Class: L} \p{Bidi_Class=Left_To_Right} (1_098_619) + \p{Bidi_Class: Left_To_Right} (Short: \p{Bc=L}) (1_098_619) \p{Bidi_Class: Left_To_Right_Embedding} (Short: \p{Bc=LRE}) (1) \p{Bidi_Class: Left_To_Right_Override} (Short: \p{Bc=LRO}) (1) \p{Bidi_Class: LRE} \p{Bidi_Class=Left_To_Right_Embedding} (1) \p{Bidi_Class: LRO} \p{Bidi_Class=Left_To_Right_Override} (1) - \p{Bidi_Class: Nonspacing_Mark} (Short: \p{Bc=NSM}) (1173) - \p{Bidi_Class: NSM} \p{Bidi_Class=Nonspacing_Mark} (1173) - \p{Bidi_Class: ON} \p{Bidi_Class=Other_Neutral} (3523) - \p{Bidi_Class: Other_Neutral} (Short: \p{Bc=ON}) (3523) + \p{Bidi_Class: Nonspacing_Mark} (Short: \p{Bc=NSM}) (1209) + \p{Bidi_Class: NSM} \p{Bidi_Class=Nonspacing_Mark} (1209) + \p{Bidi_Class: ON} \p{Bidi_Class=Other_Neutral} (4412) + \p{Bidi_Class: Other_Neutral} (Short: \p{Bc=ON}) (4412) \p{Bidi_Class: Paragraph_Separator} (Short: \p{Bc=B}) (7) \p{Bidi_Class: PDF} \p{Bidi_Class=Pop_Directional_Format} (1) \p{Bidi_Class: Pop_Directional_Format} (Short: \p{Bc=PDF}) (1) - \p{Bidi_Class: R} \p{Bidi_Class=Right_To_Left} (4441) - \p{Bidi_Class: Right_To_Left} (Short: \p{Bc=R}) (4441) + \p{Bidi_Class: R} \p{Bidi_Class=Right_To_Left} (4438) + \p{Bidi_Class: Right_To_Left} (Short: \p{Bc=R}) (4438) \p{Bidi_Class: Right_To_Left_Embedding} (Short: \p{Bc=RLE}) (1) \p{Bidi_Class: Right_To_Left_Override} (Short: \p{Bc=RLO}) (1) \p{Bidi_Class: RLE} \p{Bidi_Class=Right_To_Left_Embedding} (1) @@ -368,6 +385,8 @@ this property. \p{Blank} \h, Horizontal white space (19) \p{Blk: *} \p{Block: *} \p{Block: Aegean_Numbers} (Single: \p{InAegeanNumbers}) (64) + \p{Block: Alchemical_Symbols} (Single: \p{InAlchemicalSymbols}) + (128) \p{Block: Alphabetic_Presentation_Forms} (Single: \p{InAlphabeticPresentationForms}) (80) \p{Block: Ancient_Greek_Musical_Notation} (Single: @@ -392,7 +411,10 @@ this property. NOR \p{Is_Balinese}) (128) \p{Block: Bamum} (Single: \p{InBamum}; NOT \p{Bamum} NOR \p{Is_Bamum}) (96) + \p{Block: Bamum_Supplement} (Single: \p{InBamumSupplement}) (576) \p{Block: Basic_Latin} (Short: \p{Blk=ASCII}, \p{ASCII}) (128) + \p{Block: Batak} (Single: \p{InBatak}; NOT \p{Batak} NOR + \p{Is_Batak}) (64) \p{Block: Bengali} (Single: \p{InBengali}; NOT \p{Bengali} NOR \p{Is_Bengali}) (128) \p{Block: Block_Elements} (Single: \p{InBlockElements}) (32) @@ -400,6 +422,8 @@ this property. NOR \p{Is_Bopomofo}) (48) \p{Block: Bopomofo_Extended} (Single: \p{InBopomofoExtended}) (32) \p{Block: Box_Drawing} (Single: \p{InBoxDrawing}) (128) + \p{Block: Brahmi} (Single: \p{InBrahmi}; NOT \p{Brahmi} NOR + \p{Is_Brahmi}) (128) \p{Block: Braille_Patterns} (Single: \p{InBraillePatterns}) (256) \p{Block: Buginese} (Single: \p{InBuginese}; NOT \p{Buginese} NOR \p{Is_Buginese}) (32) @@ -440,6 +464,9 @@ this property. \p{Block: CJK_Unified_Ideographs_Extension_C} (Single: \p{InCJKUnifiedIdeographsExtensionC}) (4160) + \p{Block: CJK_Unified_Ideographs_Extension_D} (Single: + \p{InCJKUnifiedIdeographsExtensionD}) + (224) \p{Block: Combining_Diacritical_Marks} (Single: \p{InCombiningDiacriticalMarks}) (112) \p{Block: Combining_Diacritical_Marks_For_Symbols} (Short: \p{Blk= @@ -490,6 +517,7 @@ this property. \p{InEgyptianHieroglyphs}; NOT \p{Egyptian_Hieroglyphs} NOR \p{Is_Egyptian_Hieroglyphs}) (1072) + \p{Block: Emoticons} (Single: \p{InEmoticons}) (80) \p{Block: Enclosed_Alphanumeric_Supplement} (Single: \p{InEnclosedAlphanumericSupplement}) (256) @@ -503,6 +531,8 @@ this property. \p{Block: Ethiopic} (Single: \p{InEthiopic}; NOT \p{Ethiopic} NOR \p{Is_Ethiopic}) (384) \p{Block: Ethiopic_Extended} (Single: \p{InEthiopicExtended}) (96) + \p{Block: Ethiopic_Extended_A} (Single: \p{InEthiopicExtendedA}) + (48) \p{Block: Ethiopic_Supplement} (Single: \p{InEthiopicSupplement}) (32) \p{Block: General_Punctuation} (Single: \p{InGeneralPunctuation}) @@ -565,6 +595,7 @@ this property. NOR \p{Is_Javanese}) (96) \p{Block: Kaithi} (Single: \p{InKaithi}; NOT \p{Kaithi} NOR \p{Is_Kaithi}) (80) + \p{Block: Kana_Supplement} (Single: \p{InKanaSupplement}) (256) \p{Block: Kanbun} (Single: \p{InKanbun}) (16) \p{Block: Kangxi_Radicals} (Single: \p{InKangxiRadicals}) (224) \p{Block: Kannada} (Single: \p{InKannada}; NOT \p{Kannada} @@ -610,6 +641,8 @@ this property. \p{Block: Mahjong_Tiles} (Single: \p{InMahjongTiles}) (48) \p{Block: Malayalam} (Single: \p{InMalayalam}; NOT \p{Malayalam} NOR \p{Is_Malayalam}) (128) + \p{Block: Mandaic} (Single: \p{InMandaic}; NOT \p{Mandaic} + NOR \p{Is_Mandaic}) (32) \p{Block: Mathematical_Alphanumeric_Symbols} (Single: \p{InMathematicalAlphanumericSymbols}) (1024) @@ -629,6 +662,9 @@ this property. \p{Block: Miscellaneous_Symbols_And_Arrows} (Single: \p{InMiscellaneousSymbolsAndArrows}) (256) + \p{Block: Miscellaneous_Symbols_And_Pictographs} (Single: + \p{InMiscellaneousSymbolsAnd- + Pictographs}) (768) \p{Block: Miscellaneous_Technical} (Single: \p{InMiscellaneousTechnical}) (256) \p{Block: Modifier_Tone_Letters} (Single: @@ -644,7 +680,7 @@ this property. (96) \p{Block: NKo} (Single: \p{InNKo}; NOT \p{Nko} NOR \p{Is_NKo}) (64) - \p{Block: No_Block} (Single: \p{InNoBlock}) (864_192) + \p{Block: No_Block} (Single: \p{InNoBlock}) (861_664) \p{Block: Number_Forms} (Single: \p{InNumberForms}) (64) \p{Block: Ogham} (Single: \p{InOgham}; NOT \p{Ogham} NOR \p{Is_Ogham}) (32) @@ -675,6 +711,7 @@ this property. (128) \p{Block: Phonetic_Extensions_Supplement} (Single: \p{InPhoneticExtensionsSupplement}) (64) + \p{Block: Playing_Cards} (Single: \p{InPlayingCards}) (96) \p{Block: Private_Use} \p{Block=Private_Use_Area} (NOT \p{Private_Use} NOR \p{Is_Private_Use}) (6400) @@ -749,6 +786,8 @@ this property. NOR \p{Is_Tibetan}) (256) \p{Block: Tifinagh} (Single: \p{InTifinagh}; NOT \p{Tifinagh} NOR \p{Is_Tifinagh}) (80) + \p{Block: Transport_And_Map_Symbols} (Single: + \p{InTransportAndMapSymbols}) (128) \p{Block: Ugaritic} (Single: \p{InUgaritic}; NOT \p{Ugaritic} NOR \p{Is_Ugaritic}) (32) \p{Block: Unified_Canadian_Aboriginal_Syllabics} (Short: \p{Blk= @@ -771,11 +810,15 @@ this property. \p{InYijingHexagramSymbols}) (64) X \p{Block_Elements} \p{Block=Block_Elements} (32) \p{Bopo} \p{Bopomofo} (= \p{Script=Bopomofo}) (NOT - \p{Block=Bopomofo}) (65) + \p{Block=Bopomofo}) (70) \p{Bopomofo} \p{Script=Bopomofo} (Short: \p{Bopo}; NOT - \p{Block=Bopomofo}) (65) + \p{Block=Bopomofo}) (70) X \p{Bopomofo_Extended} \p{Block=Bopomofo_Extended} (32) X \p{Box_Drawing} \p{Block=Box_Drawing} (128) + \p{Brah} \p{Brahmi} (= \p{Script=Brahmi}) (NOT + \p{Block=Brahmi}) (108) + \p{Brahmi} \p{Script=Brahmi} (Short: \p{Brah}; NOT + \p{Block=Brahmi}) (108) \p{Brai} \p{Braille} (= \p{Script=Braille}) (256) \p{Braille} \p{Script=Braille} (Short: \p{Brai}) (256) X \p{Braille_Patterns} \p{Block=Braille_Patterns} (256) @@ -790,7 +833,7 @@ this property. X \p{Byzantine_Musical_Symbols} \p{Block=Byzantine_Musical_Symbols} (256) \p{C} \p{Other} (= \p{General_Category=Other}) - (1_006_956) + (1_004_868) \p{Canadian_Aboriginal} \p{Script=Canadian_Aboriginal} (Short: \p{Cans}) (710) X \p{Canadian_Syllabics} \p{Unified_Canadian_Aboriginal_Syllabics} @@ -798,15 +841,15 @@ this property. Unified_Canadian_Aboriginal_Syllabics}) (640) T \p{Canonical_Combining_Class: 0} \p{Canonical_Combining_Class= - Not_Reordered} (1_113_518) + Not_Reordered} (1_113_506) T \p{Canonical_Combining_Class: 1} \p{Canonical_Combining_Class= Overlay} (26) T \p{Canonical_Combining_Class: 7} \p{Canonical_Combining_Class= - Nukta} (11) + Nukta} (12) T \p{Canonical_Combining_Class: 8} \p{Canonical_Combining_Class= Kana_Voicing} (2) T \p{Canonical_Combining_Class: 9} \p{Canonical_Combining_Class= - Virama} (27) + Virama} (31) T \p{Canonical_Combining_Class: 10} (Short: \p{Ccc=10}) (1) T \p{Canonical_Combining_Class: 11} (Short: \p{Ccc=11}) (1) T \p{Canonical_Combining_Class: 12} (Short: \p{Ccc=12}) (1) @@ -854,7 +897,7 @@ this property. T \p{Canonical_Combining_Class: 218} \p{Canonical_Combining_Class= Below_Left} (1) T \p{Canonical_Combining_Class: 220} \p{Canonical_Combining_Class= - Below} (117) + Below} (121) T \p{Canonical_Combining_Class: 222} \p{Canonical_Combining_Class= Below_Right} (4) T \p{Canonical_Combining_Class: 224} \p{Canonical_Combining_Class= @@ -864,18 +907,18 @@ this property. T \p{Canonical_Combining_Class: 228} \p{Canonical_Combining_Class= Above_Left} (3) T \p{Canonical_Combining_Class: 230} \p{Canonical_Combining_Class= - Above} (318) + Above} (320) T \p{Canonical_Combining_Class: 232} \p{Canonical_Combining_Class= Above_Right} (4) T \p{Canonical_Combining_Class: 233} \p{Canonical_Combining_Class= - Double_Below} (3) + Double_Below} (4) T \p{Canonical_Combining_Class: 234} \p{Canonical_Combining_Class= Double_Above} (5) T \p{Canonical_Combining_Class: 240} \p{Canonical_Combining_Class= Iota_Subscript} (1) \p{Canonical_Combining_Class: A} \p{Canonical_Combining_Class= - Above} (318) - \p{Canonical_Combining_Class: Above} (Short: \p{Ccc=A}) (318) + Above} (320) + \p{Canonical_Combining_Class: Above} (Short: \p{Ccc=A}) (320) \p{Canonical_Combining_Class: Above_Left} (Short: \p{Ccc=AL}) (3) \p{Canonical_Combining_Class: Above_Right} (Short: \p{Ccc=AR}) (4) \p{Canonical_Combining_Class: AL} \p{Canonical_Combining_Class= @@ -899,8 +942,8 @@ this property. \p{Canonical_Combining_Class: Attached_Below_Left} (Short: \p{Ccc= ATBL}) (0) \p{Canonical_Combining_Class: B} \p{Canonical_Combining_Class= - Below} (117) - \p{Canonical_Combining_Class: Below} (Short: \p{Ccc=B}) (117) + Below} (121) + \p{Canonical_Combining_Class: Below} (Short: \p{Ccc=B}) (121) \p{Canonical_Combining_Class: Below_Left} (Short: \p{Ccc=BL}) (1) \p{Canonical_Combining_Class: Below_Right} (Short: \p{Ccc=BR}) (4) \p{Canonical_Combining_Class: BL} \p{Canonical_Combining_Class= @@ -910,9 +953,9 @@ this property. \p{Canonical_Combining_Class: DA} \p{Canonical_Combining_Class= Double_Above} (5) \p{Canonical_Combining_Class: DB} \p{Canonical_Combining_Class= - Double_Below} (3) + Double_Below} (4) \p{Canonical_Combining_Class: Double_Above} (Short: \p{Ccc=DA}) (5) - \p{Canonical_Combining_Class: Double_Below} (Short: \p{Ccc=DB}) (3) + \p{Canonical_Combining_Class: Double_Below} (Short: \p{Ccc=DB}) (4) \p{Canonical_Combining_Class: Iota_Subscript} (Short: \p{Ccc=IS}) (1) \p{Canonical_Combining_Class: IS} \p{Canonical_Combining_Class= @@ -924,35 +967,35 @@ this property. Left} (2) \p{Canonical_Combining_Class: Left} (Short: \p{Ccc=L}) (2) \p{Canonical_Combining_Class: NK} \p{Canonical_Combining_Class= - Nukta} (11) + Nukta} (12) \p{Canonical_Combining_Class: Not_Reordered} (Short: \p{Ccc=NR}) - (1_113_518) + (1_113_506) \p{Canonical_Combining_Class: NR} \p{Canonical_Combining_Class= - Not_Reordered} (1_113_518) - \p{Canonical_Combining_Class: Nukta} (Short: \p{Ccc=NK}) (11) + Not_Reordered} (1_113_506) + \p{Canonical_Combining_Class: Nukta} (Short: \p{Ccc=NK}) (12) \p{Canonical_Combining_Class: OV} \p{Canonical_Combining_Class= Overlay} (26) \p{Canonical_Combining_Class: Overlay} (Short: \p{Ccc=OV}) (26) \p{Canonical_Combining_Class: R} \p{Canonical_Combining_Class= Right} (1) \p{Canonical_Combining_Class: Right} (Short: \p{Ccc=R}) (1) - \p{Canonical_Combining_Class: Virama} (Short: \p{Ccc=VR}) (27) + \p{Canonical_Combining_Class: Virama} (Short: \p{Ccc=VR}) (31) \p{Canonical_Combining_Class: VR} \p{Canonical_Combining_Class= - Virama} (27) + Virama} (31) \p{Cans} \p{Canadian_Aboriginal} (= \p{Script= Canadian_Aboriginal}) (710) \p{Cari} \p{Carian} (= \p{Script=Carian}) (NOT \p{Block=Carian}) (49) \p{Carian} \p{Script=Carian} (Short: \p{Cari}; NOT \p{Block=Carian}) (49) - \p{Case_Ignorable} \p{Case_Ignorable=Y} (Short: \p{CI}) (1632) - \p{Case_Ignorable: N*} (Short: \p{CI=N}, \P{CI}) (1_112_480) - \p{Case_Ignorable: Y*} (Short: \p{CI=Y}, \p{CI}) (1632) - \p{Cased} \p{Cased=Y} (3408) - \p{Cased: N*} (Single: \P{Cased}) (1_110_704) - \p{Cased: Y*} (Single: \p{Cased}) (3408) + \p{Case_Ignorable} \p{Case_Ignorable=Y} (Short: \p{CI}) (1692) + \p{Case_Ignorable: N*} (Short: \p{CI=N}, \P{CI}) (1_112_420) + \p{Case_Ignorable: Y*} (Short: \p{CI=Y}, \p{CI}) (1692) + \p{Cased} \p{Cased=Y} (3427) + \p{Cased: N*} (Single: \P{Cased}) (1_110_685) + \p{Cased: Y*} (Single: \p{Cased}) (3427) \p{Cased_Letter} \p{General_Category=Cased_Letter} (Short: - \p{LC}) (3207) + \p{LC}) (3226) \p{Category: *} \p{General_Category: *} \p{Cc} \p{Cntrl} (= \p{General_Category=Control}) (65) @@ -964,44 +1007,44 @@ this property. (140) \p{Cham} \p{Script=Cham} (NOT \p{Block=Cham}) (83) \p{Changes_When_Casefolded} \p{Changes_When_Casefolded=Y} (Short: - \p{CWCF}) (1093) + \p{CWCF}) (1102) \p{Changes_When_Casefolded: N*} (Short: \p{CWCF=N}, \P{CWCF}) - (1_113_019) + (1_113_010) \p{Changes_When_Casefolded: Y*} (Short: \p{CWCF=Y}, \p{CWCF}) - (1093) + (1102) \p{Changes_When_Casemapped} \p{Changes_When_Casemapped=Y} (Short: - \p{CWCM}) (2110) + \p{CWCM}) (2128) \p{Changes_When_Casemapped: N*} (Short: \p{CWCM=N}, \P{CWCM}) - (1_112_002) + (1_111_984) \p{Changes_When_Casemapped: Y*} (Short: \p{CWCM=Y}, \p{CWCM}) - (2110) + (2128) \p{Changes_When_Lowercased} \p{Changes_When_Lowercased=Y} (Short: - \p{CWL}) (1029) + \p{CWL}) (1038) \p{Changes_When_Lowercased: N*} (Short: \p{CWL=N}, \P{CWL}) - (1_113_083) - \p{Changes_When_Lowercased: Y*} (Short: \p{CWL=Y}, \p{CWL}) (1029) + (1_113_074) + \p{Changes_When_Lowercased: Y*} (Short: \p{CWL=Y}, \p{CWL}) (1038) \p{Changes_When_NFKC_Casefolded} \p{Changes_When_NFKC_Casefolded= - Y} (Short: \p{CWKCF}) (9740) + Y} (Short: \p{CWKCF}) (9792) \p{Changes_When_NFKC_Casefolded: N*} (Short: \p{CWKCF=N}, - \P{CWKCF}) (1_104_372) + \P{CWKCF}) (1_104_320) \p{Changes_When_NFKC_Casefolded: Y*} (Short: \p{CWKCF=Y}, - \p{CWKCF}) (9740) + \p{CWKCF}) (9792) \p{Changes_When_Titlecased} \p{Changes_When_Titlecased=Y} (Short: - \p{CWT}) (1085) + \p{CWT}) (1094) \p{Changes_When_Titlecased: N*} (Short: \p{CWT=N}, \P{CWT}) - (1_113_027) - \p{Changes_When_Titlecased: Y*} (Short: \p{CWT=Y}, \p{CWT}) (1085) + (1_113_018) + \p{Changes_When_Titlecased: Y*} (Short: \p{CWT=Y}, \p{CWT}) (1094) \p{Changes_When_Uppercased} \p{Changes_When_Uppercased=Y} (Short: - \p{CWU}) (1112) + \p{CWU}) (1121) \p{Changes_When_Uppercased: N*} (Short: \p{CWU=N}, \P{CWU}) - (1_113_000) - \p{Changes_When_Uppercased: Y*} (Short: \p{CWU=Y}, \p{CWU}) (1112) + (1_112_991) + \p{Changes_When_Uppercased: Y*} (Short: \p{CWU=Y}, \p{CWU}) (1121) \p{Cher} \p{Cherokee} (= \p{Script=Cherokee}) (NOT \p{Block=Cherokee}) (85) \p{Cherokee} \p{Script=Cherokee} (Short: \p{Cher}; NOT \p{Block=Cherokee}) (85) \p{CI} \p{Case_Ignorable} (= \p{Case_Ignorable= - Y}) (1632) + Y}) (1692) \p{CI: *} \p{Case_Ignorable: *} X \p{CJK_Compatibility} \p{Block=CJK_Compatibility} (256) X \p{CJK_Compatibility_Forms} \p{Block=CJK_Compatibility_Forms} (32) @@ -1025,10 +1068,12 @@ this property. X \p{CJK_Unified_Ideographs_Extension_C} \p{Block= CJK_Unified_Ideographs_Extension_C} (4160) + X \p{CJK_Unified_Ideographs_Extension_D} \p{Block= + CJK_Unified_Ideographs_Extension_D} (224) \p{Close_Punctuation} \p{General_Category=Close_Punctuation} (Short: \p{Pe}) (71) \p{Cn} \p{Unassigned} (= \p{General_Category= - Unassigned}) (867_235) + Unassigned}) (865_147) \p{Cntrl} \p{General_Category=Control} Control characters (Short: \p{Cc}) (65) \p{Co} \p{Private_Use} (= \p{General_Category= @@ -1049,7 +1094,7 @@ this property. Symbols} (= \p{Block= Combining_Diacritical_Marks_For_- Symbols}) (48) - \p{Common} \p{Script=Common} (Short: \p{Zyyy}) (5395) + \p{Common} \p{Script=Common} (Short: \p{Zyyy}) (6379) X \p{Common_Indic_Number_Forms} \p{Block=Common_Indic_Number_Forms} (16) \p{Comp_Ex} \p{Full_Composition_Exclusion} (= @@ -1078,52 +1123,52 @@ this property. X \p{Cuneiform_Numbers_And_Punctuation} \p{Block= Cuneiform_Numbers_And_Punctuation} (128) \p{Currency_Symbol} \p{General_Category=Currency_Symbol} - (Short: \p{Sc}) (46) + (Short: \p{Sc}) (47) X \p{Currency_Symbols} \p{Block=Currency_Symbols} (48) \p{CWCF} \p{Changes_When_Casefolded} (= - \p{Changes_When_Casefolded=Y}) (1093) + \p{Changes_When_Casefolded=Y}) (1102) \p{CWCF: *} \p{Changes_When_Casefolded: *} \p{CWCM} \p{Changes_When_Casemapped} (= - \p{Changes_When_Casemapped=Y}) (2110) + \p{Changes_When_Casemapped=Y}) (2128) \p{CWCM: *} \p{Changes_When_Casemapped: *} \p{CWKCF} \p{Changes_When_NFKC_Casefolded} (= \p{Changes_When_NFKC_Casefolded=Y}) - (9740) + (9792) \p{CWKCF: *} \p{Changes_When_NFKC_Casefolded: *} \p{CWL} \p{Changes_When_Lowercased} (= - \p{Changes_When_Lowercased=Y}) (1029) + \p{Changes_When_Lowercased=Y}) (1038) \p{CWL: *} \p{Changes_When_Lowercased: *} \p{CWT} \p{Changes_When_Titlecased} (= - \p{Changes_When_Titlecased=Y}) (1085) + \p{Changes_When_Titlecased=Y}) (1094) \p{CWT: *} \p{Changes_When_Titlecased: *} \p{CWU} \p{Changes_When_Uppercased} (= - \p{Changes_When_Uppercased=Y}) (1112) + \p{Changes_When_Uppercased=Y}) (1121) \p{CWU: *} \p{Changes_When_Uppercased: *} \p{Cypriot} \p{Script=Cypriot} (Short: \p{Cprt}) (55) X \p{Cypriot_Syllabary} \p{Block=Cypriot_Syllabary} (64) \p{Cyrillic} \p{Script=Cyrillic} (Short: \p{Cyrl}; NOT - \p{Block=Cyrillic}) (404) + \p{Block=Cyrillic}) (408) X \p{Cyrillic_Extended_A} \p{Block=Cyrillic_Extended_A} (32) X \p{Cyrillic_Extended_B} \p{Block=Cyrillic_Extended_B} (96) X \p{Cyrillic_Supplement} \p{Block=Cyrillic_Supplement} (48) X \p{Cyrillic_Supplementary} \p{Cyrillic_Supplement} (= \p{Block= Cyrillic_Supplement}) (48) \p{Cyrl} \p{Cyrillic} (= \p{Script=Cyrillic}) (NOT - \p{Block=Cyrillic}) (404) + \p{Block=Cyrillic}) (408) \p{Dash} \p{Dash=Y} (25) \p{Dash: N*} (Single: \P{Dash}) (1_114_087) \p{Dash: Y*} (Single: \p{Dash}) (25) \p{Dash_Punctuation} \p{General_Category=Dash_Punctuation} (Short: \p{Pd}) (21) \p{Decimal_Number} \p{Digit} (= \p{General_Category= - Decimal_Number}) (411) + Decimal_Number}) (420) \p{Decomposition_Type: Can} \p{Decomposition_Type=Canonical} (13_221) \p{Decomposition_Type: Canonical} (Short: \p{Dt=Can}) (13_221) - \p{Decomposition_Type: Circle} (Short: \p{Dt=Enc}) (238) + \p{Decomposition_Type: Circle} (Short: \p{Dt=Enc}) (240) \p{Decomposition_Type: Com} \p{Decomposition_Type=Compat} (720) \p{Decomposition_Type: Compat} (Short: \p{Dt=Com}) (720) - \p{Decomposition_Type: Enc} \p{Decomposition_Type=Circle} (238) + \p{Decomposition_Type: Enc} \p{Decomposition_Type=Circle} (240) \p{Decomposition_Type: Fin} \p{Decomposition_Type=Final} (240) \p{Decomposition_Type: Final} (Short: \p{Dt=Fin}) (240) \p{Decomposition_Type: Font} (Short: \p{Dt=Font}) (1043) @@ -1140,16 +1185,16 @@ this property. \p{Decomposition_Type: Nb} \p{Decomposition_Type=Nobreak} (5) \p{Decomposition_Type: Nobreak} (Short: \p{Dt=Nb}) (5) \p{Decomposition_Type: Non_Canon} \p{Decomposition_Type= - Non_Canonical} (Perl extension) (3467) + Non_Canonical} (Perl extension) (3510) \p{Decomposition_Type: Non_Canonical} Union of all non-canonical decompositions (Short: \p{Dt=NonCanon}) - (Perl extension) (3467) - \p{Decomposition_Type: None} (Short: \p{Dt=None}) (1_097_424) + (Perl extension) (3510) + \p{Decomposition_Type: None} (Short: \p{Dt=None}) (1_097_381) \p{Decomposition_Type: Small} (Short: \p{Dt=Sml}) (26) \p{Decomposition_Type: Sml} \p{Decomposition_Type=Small} (26) - \p{Decomposition_Type: Sqr} \p{Decomposition_Type=Square} (251) - \p{Decomposition_Type: Square} (Short: \p{Dt=Sqr}) (251) - \p{Decomposition_Type: Sub} (Short: \p{Dt=Sub}) (30) + \p{Decomposition_Type: Sqr} \p{Decomposition_Type=Square} (284) + \p{Decomposition_Type: Square} (Short: \p{Dt=Sqr}) (284) + \p{Decomposition_Type: Sub} (Short: \p{Dt=Sub}) (38) \p{Decomposition_Type: Sup} \p{Decomposition_Type=Super} (142) \p{Decomposition_Type: Super} (Short: \p{Dt=Sup}) (142) \p{Decomposition_Type: Vert} \p{Decomposition_Type=Vertical} (35) @@ -1161,16 +1206,16 @@ this property. (1_109_945) \p{Default_Ignorable_Code_Point: Y*} (Short: \p{DI=Y}, \p{DI}) (4167) - \p{Dep} \p{Deprecated} (= \p{Deprecated=Y}) (110) + \p{Dep} \p{Deprecated} (= \p{Deprecated=Y}) (111) \p{Dep: *} \p{Deprecated: *} - \p{Deprecated} \p{Deprecated=Y} (Short: \p{Dep}) (110) - \p{Deprecated: N*} (Short: \p{Dep=N}, \P{Dep}) (1_114_002) - \p{Deprecated: Y*} (Short: \p{Dep=Y}, \p{Dep}) (110) + \p{Deprecated} \p{Deprecated=Y} (Short: \p{Dep}) (111) + \p{Deprecated: N*} (Short: \p{Dep=N}, \P{Dep}) (1_114_001) + \p{Deprecated: Y*} (Short: \p{Dep=Y}, \p{Dep}) (111) \p{Deseret} \p{Script=Deseret} (Short: \p{Dsrt}) (80) \p{Deva} \p{Devanagari} (= \p{Script=Devanagari}) - (NOT \p{Block=Devanagari}) (140) + (NOT \p{Block=Devanagari}) (150) \p{Devanagari} \p{Script=Devanagari} (Short: \p{Deva}; - NOT \p{Block=Devanagari}) (140) + NOT \p{Block=Devanagari}) (150) X \p{Devanagari_Extended} \p{Block=Devanagari_Extended} (32) \p{DI} \p{Default_Ignorable_Code_Point} (= \p{Default_Ignorable_Code_Point=Y}) @@ -1181,32 +1226,33 @@ this property. \p{Diacritic} \p{Diacritic=Y} (Short: \p{Dia}) (639) \p{Diacritic: N*} (Short: \p{Dia=N}, \P{Dia}) (1_113_473) \p{Diacritic: Y*} (Short: \p{Dia=Y}, \p{Dia}) (639) - \p{Digit} \p{General_Category=Decimal_Number} \d, - extended beyond just [0-9] (Short: - \p{Nd}) (411) + \p{Digit} \p{General_Category=Decimal_Number} [0-9] + + all other decimal digits (Short: + \p{Nd}) (420) X \p{Dingbats} \p{Block=Dingbats} (192) X \p{Domino_Tiles} \p{Block=Domino_Tiles} (112) \p{Dsrt} \p{Deseret} (= \p{Script=Deseret}) (80) \p{Dt: *} \p{Decomposition_Type: *} \p{Ea: *} \p{East_Asian_Width: *} - \p{East_Asian_Width: A} \p{East_Asian_Width=Ambiguous} (138_666) - \p{East_Asian_Width: Ambiguous} (Short: \p{Ea=A}) (138_666) + \p{East_Asian_Width: A} \p{East_Asian_Width=Ambiguous} (138_746) + \p{East_Asian_Width: Ambiguous} (Short: \p{Ea=A}) (138_746) \p{East_Asian_Width: F} \p{East_Asian_Width=Fullwidth} (104) \p{East_Asian_Width: Fullwidth} (Short: \p{Ea=F}) (104) \p{East_Asian_Width: H} \p{East_Asian_Width=Halfwidth} (123) \p{East_Asian_Width: Halfwidth} (Short: \p{Ea=H}) (123) - \p{East_Asian_Width: N} \p{East_Asian_Width=Neutral} (801_909) + \p{East_Asian_Width: N} \p{East_Asian_Width=Neutral} (801_811) \p{East_Asian_Width: Na} \p{East_Asian_Width=Narrow} (111) \p{East_Asian_Width: Narrow} (Short: \p{Ea=Na}) (111) - \p{East_Asian_Width: Neutral} (Short: \p{Ea=N}) (801_909) - \p{East_Asian_Width: W} \p{East_Asian_Width=Wide} (173_199) - \p{East_Asian_Width: Wide} (Short: \p{Ea=W}) (173_199) + \p{East_Asian_Width: Neutral} (Short: \p{Ea=N}) (801_811) + \p{East_Asian_Width: W} \p{East_Asian_Width=Wide} (173_217) + \p{East_Asian_Width: Wide} (Short: \p{Ea=W}) (173_217) \p{Egyp} \p{Egyptian_Hieroglyphs} (= \p{Script= Egyptian_Hieroglyphs}) (NOT \p{Block= Egyptian_Hieroglyphs}) (1071) \p{Egyptian_Hieroglyphs} \p{Script=Egyptian_Hieroglyphs} (Short: \p{Egyp}; NOT \p{Block= Egyptian_Hieroglyphs}) (1071) + X \p{Emoticons} \p{Block=Emoticons} (80) X \p{Enclosed_Alphanumeric_Supplement} \p{Block= Enclosed_Alphanumeric_Supplement} (256) X \p{Enclosed_Alphanumerics} \p{Block=Enclosed_Alphanumerics} (160) @@ -1215,12 +1261,13 @@ this property. X \p{Enclosed_Ideographic_Supplement} \p{Block= Enclosed_Ideographic_Supplement} (256) \p{Enclosing_Mark} \p{General_Category=Enclosing_Mark} - (Short: \p{Me}) (13) + (Short: \p{Me}) (12) \p{Ethi} \p{Ethiopic} (= \p{Script=Ethiopic}) (NOT - \p{Block=Ethiopic}) (461) + \p{Block=Ethiopic}) (495) \p{Ethiopic} \p{Script=Ethiopic} (Short: \p{Ethi}; NOT - \p{Block=Ethiopic}) (461) + \p{Block=Ethiopic}) (495) X \p{Ethiopic_Extended} \p{Block=Ethiopic_Extended} (96) + X \p{Ethiopic_Extended_A} \p{Block=Ethiopic_Extended_A} (48) X \p{Ethiopic_Supplement} \p{Block=Ethiopic_Supplement} (32) \p{Ext} \p{Extender} (= \p{Extender=Y}) (28) \p{Ext: *} \p{Extender: *} @@ -1239,14 +1286,14 @@ this property. \p{CompEx}) (1118) \p{Gc: *} \p{General_Category: *} \p{GCB: *} \p{Grapheme_Cluster_Break: *} - \p{General_Category: C} \p{General_Category=Other} (1_006_956) + \p{General_Category: C} \p{General_Category=Other} (1_004_868) \p{General_Category: Cased_Letter} [\p{Ll}\p{Lu}\p{Lt}] (Short: - \p{Gc=LC}, \p{LC}) (3207) + \p{Gc=LC}, \p{LC}) (3226) \p{General_Category: Cc} \p{General_Category=Control} (65) \p{General_Category: Cf} \p{General_Category=Format} (140) \p{General_Category: Close_Punctuation} (Short: \p{Gc=Pe}, \p{Pe}) (71) - \p{General_Category: Cn} \p{General_Category=Unassigned} (867_235) + \p{General_Category: Cn} \p{General_Category=Unassigned} (865_147) \p{General_Category: Cntrl} \p{General_Category=Control} (65) \p{General_Category: Co} \p{General_Category=Private_Use} (137_468) \p{General_Category: Connector_Punctuation} (Short: \p{Gc=Pc}, @@ -1254,66 +1301,69 @@ this property. \p{General_Category: Control} (Short: \p{Gc=Cc}, \p{Cc}) (65) \p{General_Category: Cs} \p{General_Category=Surrogate} (2048) \p{General_Category: Currency_Symbol} (Short: \p{Gc=Sc}, \p{Sc}) - (46) + (47) \p{General_Category: Dash_Punctuation} (Short: \p{Gc=Pd}, \p{Pd}) (21) \p{General_Category: Decimal_Number} (Short: \p{Gc=Nd}, \p{Nd}) - (411) + (420) \p{General_Category: Digit} \p{General_Category=Decimal_Number} - (411) + (420) \p{General_Category: Enclosing_Mark} (Short: \p{Gc=Me}, \p{Me}) - (13) + (12) \p{General_Category: Final_Punctuation} (Short: \p{Gc=Pf}, \p{Pf}) (10) \p{General_Category: Format} (Short: \p{Gc=Cf}, \p{Cf}) (140) \p{General_Category: Initial_Punctuation} (Short: \p{Gc=Pi}, \p{Pi}) (12) - \p{General_Category: L} \p{General_Category=Letter} (99_537) - X \p{General_Category: L&} \p{General_Category=Cased_Letter} (3207) - X \p{General_Category: L_} \p{General_Category=Cased_Letter} (3207) - \p{General_Category: LC} \p{General_Category=Cased_Letter} (3207) - \p{General_Category: Letter} (Short: \p{Gc=L}, \p{L}) (99_537) + \p{General_Category: L} \p{General_Category=Letter} (100_520) + X \p{General_Category: L&} \p{General_Category=Cased_Letter} (3226) + X \p{General_Category: L_} \p{General_Category=Cased_Letter} (3226) + \p{General_Category: LC} \p{General_Category=Cased_Letter} (3226) + \p{General_Category: Letter} (Short: \p{Gc=L}, \p{L}) (100_520) \p{General_Category: Letter_Number} (Short: \p{Gc=Nl}, \p{Nl}) (224) \p{General_Category: Line_Separator} (Short: \p{Gc=Zl}, \p{Zl}) (1) \p{General_Category: Ll} \p{General_Category=Lowercase_Letter} - (1749) - \p{General_Category: Lm} \p{General_Category=Modifier_Letter} (202) - \p{General_Category: Lo} \p{General_Category=Other_Letter} (96_128) - \p{General_Category: Lowercase_Letter} (Short: \p{Gc=Ll}, \p{Ll}) - (1749) - \p{General_Category: Lt} \p{General_Category=Titlecase_Letter} (31) + (/i= General_Category=Cased_Letter) + (1759) + \p{General_Category: Lm} \p{General_Category=Modifier_Letter} (210) + \p{General_Category: Lo} \p{General_Category=Other_Letter} (97_084) + \p{General_Category: Lowercase_Letter} (Short: \p{Gc=Ll}, \p{Ll}; + /i= General_Category=Cased_Letter) (1759) + \p{General_Category: Lt} \p{General_Category=Titlecase_Letter} + (/i= General_Category=Cased_Letter) (31) \p{General_Category: Lu} \p{General_Category=Uppercase_Letter} - (1427) - \p{General_Category: M} \p{General_Category=Mark} (1451) - \p{General_Category: Mark} (Short: \p{Gc=M}, \p{M}) (1451) - \p{General_Category: Math_Symbol} (Short: \p{Gc=Sm}, \p{Sm}) (945) - \p{General_Category: Mc} \p{General_Category=Spacing_Mark} (276) - \p{General_Category: Me} \p{General_Category=Enclosing_Mark} (13) + (/i= General_Category=Cased_Letter) + (1436) + \p{General_Category: M} \p{General_Category=Mark} (1498) + \p{General_Category: Mark} (Short: \p{Gc=M}, \p{M}) (1498) + \p{General_Category: Math_Symbol} (Short: \p{Gc=Sm}, \p{Sm}) (948) + \p{General_Category: Mc} \p{General_Category=Spacing_Mark} (287) + \p{General_Category: Me} \p{General_Category=Enclosing_Mark} (12) \p{General_Category: Mn} \p{General_Category=Nonspacing_Mark} - (1162) + (1199) \p{General_Category: Modifier_Letter} (Short: \p{Gc=Lm}, \p{Lm}) - (202) + (210) \p{General_Category: Modifier_Symbol} (Short: \p{Gc=Sk}, \p{Sk}) - (99) - \p{General_Category: N} \p{General_Category=Number} (1064) - \p{General_Category: Nd} \p{General_Category=Decimal_Number} (411) + (115) + \p{General_Category: N} \p{General_Category=Number} (1100) + \p{General_Category: Nd} \p{General_Category=Decimal_Number} (420) \p{General_Category: Nl} \p{General_Category=Letter_Number} (224) - \p{General_Category: No} \p{General_Category=Other_Number} (429) + \p{General_Category: No} \p{General_Category=Other_Number} (456) \p{General_Category: Nonspacing_Mark} (Short: \p{Gc=Mn}, \p{Mn}) - (1162) - \p{General_Category: Number} (Short: \p{Gc=N}, \p{N}) (1064) + (1199) + \p{General_Category: Number} (Short: \p{Gc=N}, \p{N}) (1100) \p{General_Category: Open_Punctuation} (Short: \p{Gc=Ps}, \p{Ps}) (72) - \p{General_Category: Other} (Short: \p{Gc=C}, \p{C}) (1_006_956) + \p{General_Category: Other} (Short: \p{Gc=C}, \p{C}) (1_004_868) \p{General_Category: Other_Letter} (Short: \p{Gc=Lo}, \p{Lo}) - (96_128) - \p{General_Category: Other_Number} (Short: \p{Gc=No}, \p{No}) (429) + (97_084) + \p{General_Category: Other_Number} (Short: \p{Gc=No}, \p{No}) (456) \p{General_Category: Other_Punctuation} (Short: \p{Gc=Po}, \p{Po}) - (389) + (402) \p{General_Category: Other_Symbol} (Short: \p{Gc=So}, \p{So}) - (3409) - \p{General_Category: P} \p{General_Category=Punctuation} (585) + (4398) + \p{General_Category: P} \p{General_Category=Punctuation} (598) \p{General_Category: Paragraph_Separator} (Short: \p{Gc=Zp}, \p{Zp}) (1) \p{General_Category: Pc} \p{General_Category= @@ -1326,30 +1376,29 @@ this property. \p{General_Category: Pi} \p{General_Category=Initial_Punctuation} (12) \p{General_Category: Po} \p{General_Category=Other_Punctuation} - (389) + (402) \p{General_Category: Private_Use} (Short: \p{Gc=Co}, \p{Co}) (137_468) \p{General_Category: Ps} \p{General_Category=Open_Punctuation} (72) - \p{General_Category: Punct} \p{General_Category=Punctuation} (585) - \p{General_Category: Punctuation} (Short: \p{Gc=P}, \p{P}) (585) - \p{General_Category: S} \p{General_Category=Symbol} (4499) - \p{General_Category: Sc} \p{General_Category=Currency_Symbol} (46) + \p{General_Category: Punct} \p{General_Category=Punctuation} (598) + \p{General_Category: Punctuation} (Short: \p{Gc=P}, \p{P}) (598) + \p{General_Category: S} \p{General_Category=Symbol} (5508) + \p{General_Category: Sc} \p{General_Category=Currency_Symbol} (47) \p{General_Category: Separator} (Short: \p{Gc=Z}, \p{Z}) (20) - \p{General_Category: Sk} \p{General_Category=Modifier_Symbol} (99) - \p{General_Category: Sm} \p{General_Category=Math_Symbol} (945) - \p{General_Category: So} \p{General_Category=Other_Symbol} (3409) + \p{General_Category: Sk} \p{General_Category=Modifier_Symbol} (115) + \p{General_Category: Sm} \p{General_Category=Math_Symbol} (948) + \p{General_Category: So} \p{General_Category=Other_Symbol} (4398) \p{General_Category: Space_Separator} (Short: \p{Gc=Zs}, \p{Zs}) (18) - \p{General_Category: Spacing_Mark} (Short: \p{Gc=Mc}, \p{Mc}) (276) - \p{General_Category: Surrogate} Mostly not usable in Perl. (Short: - \p{Gc=Cs}, \p{Cs}) (2048) - \p{General_Category: Symbol} (Short: \p{Gc=S}, \p{S}) (4499) - \p{General_Category: Titlecase_Letter} (Short: \p{Gc=Lt}, \p{Lt}) - (31) + \p{General_Category: Spacing_Mark} (Short: \p{Gc=Mc}, \p{Mc}) (287) + \p{General_Category: Surrogate} (Short: \p{Gc=Cs}, \p{Cs}) (2048) + \p{General_Category: Symbol} (Short: \p{Gc=S}, \p{S}) (5508) + \p{General_Category: Titlecase_Letter} (Short: \p{Gc=Lt}, \p{Lt}; + /i= General_Category=Cased_Letter) (31) \p{General_Category: Unassigned} (Short: \p{Gc=Cn}, \p{Cn}) - (867_235) - \p{General_Category: Uppercase_Letter} (Short: \p{Gc=Lu}, \p{Lu}) - (1427) + (865_147) + \p{General_Category: Uppercase_Letter} (Short: \p{Gc=Lu}, \p{Lu}; + /i= General_Category=Cased_Letter) (1436) \p{General_Category: Z} \p{General_Category=Separator} (20) \p{General_Category: Zl} \p{General_Category=Line_Separator} (1) \p{General_Category: Zp} \p{General_Category=Paragraph_Separator} @@ -1371,43 +1420,43 @@ this property. \p{Gothic} \p{Script=Gothic} (Short: \p{Goth}; NOT \p{Block=Gothic}) (27) \p{Gr_Base} \p{Grapheme_Base} (= \p{Grapheme_Base=Y}) - (105_958) + (108_010) \p{Gr_Base: *} \p{Grapheme_Base: *} \p{Gr_Ext} \p{Grapheme_Extend} (= \p{Grapheme_Extend= - Y}) (1198) + Y}) (1234) \p{Gr_Ext: *} \p{Grapheme_Extend: *} - \p{Graph} Characters that are graphical (244_744) + \p{Graph} Characters that are graphical (246_832) \p{Grapheme_Base} \p{Grapheme_Base=Y} (Short: \p{GrBase}) - (105_958) + (108_010) \p{Grapheme_Base: N*} (Short: \p{GrBase=N}, \P{GrBase}) - (1_008_154) - \p{Grapheme_Base: Y*} (Short: \p{GrBase=Y}, \p{GrBase}) (105_958) + (1_006_102) + \p{Grapheme_Base: Y*} (Short: \p{GrBase=Y}, \p{GrBase}) (108_010) \p{Grapheme_Cluster_Break: CN} \p{Grapheme_Cluster_Break=Control} (203) \p{Grapheme_Cluster_Break: Control} (Short: \p{GCB=CN}) (203) \p{Grapheme_Cluster_Break: CR} (Short: \p{GCB=CR}) (1) \p{Grapheme_Cluster_Break: EX} \p{Grapheme_Cluster_Break=Extend} - (1205) - \p{Grapheme_Cluster_Break: Extend} (Short: \p{GCB=EX}) (1205) + (1234) + \p{Grapheme_Cluster_Break: Extend} (Short: \p{GCB=EX}) (1234) \p{Grapheme_Cluster_Break: L} (Short: \p{GCB=L}) (125) \p{Grapheme_Cluster_Break: LF} (Short: \p{GCB=LF}) (1) \p{Grapheme_Cluster_Break: LV} (Short: \p{GCB=LV}) (399) \p{Grapheme_Cluster_Break: LVT} (Short: \p{GCB=LVT}) (10_773) - \p{Grapheme_Cluster_Break: Other} (Short: \p{GCB=XX}) (1_100_901) + \p{Grapheme_Cluster_Break: Other} (Short: \p{GCB=XX}) (1_100_854) \p{Grapheme_Cluster_Break: PP} \p{Grapheme_Cluster_Break=Prepend} (15) \p{Grapheme_Cluster_Break: Prepend} (Short: \p{GCB=PP}) (15) \p{Grapheme_Cluster_Break: SM} \p{Grapheme_Cluster_Break= - SpacingMark} (257) - \p{Grapheme_Cluster_Break: SpacingMark} (Short: \p{GCB=SM}) (257) + SpacingMark} (275) + \p{Grapheme_Cluster_Break: SpacingMark} (Short: \p{GCB=SM}) (275) \p{Grapheme_Cluster_Break: T} (Short: \p{GCB=T}) (137) \p{Grapheme_Cluster_Break: V} (Short: \p{GCB=V}) (95) \p{Grapheme_Cluster_Break: XX} \p{Grapheme_Cluster_Break=Other} - (1_100_901) + (1_100_854) \p{Grapheme_Extend} \p{Grapheme_Extend=Y} (Short: \p{GrExt}) - (1198) - \p{Grapheme_Extend: N*} (Short: \p{GrExt=N}, \P{GrExt}) (1_112_914) - \p{Grapheme_Extend: Y*} (Short: \p{GrExt=Y}, \p{GrExt}) (1198) + (1234) + \p{Grapheme_Extend: N*} (Short: \p{GrExt=N}, \P{GrExt}) (1_112_878) + \p{Grapheme_Extend: Y*} (Short: \p{GrExt=Y}, \p{GrExt}) (1234) \p{Greek} \p{Script=Greek} (Short: \p{Grek}; NOT \p{Greek_And_Coptic}) (511) X \p{Greek_And_Coptic} \p{Block=Greek_And_Coptic} (Short: @@ -1425,10 +1474,10 @@ this property. \p{Block=Gurmukhi}) (79) X \p{Halfwidth_And_Fullwidth_Forms} \p{Block= Halfwidth_And_Fullwidth_Forms} (240) - \p{Han} \p{Script=Han} (75_738) - \p{Hang} \p{Hangul} (= \p{Script=Hangul}) (11_737) + \p{Han} \p{Script=Han} (75_960) + \p{Hang} \p{Hangul} (= \p{Script=Hangul}) (11_739) \p{Hangul} \p{Script=Hangul} (Short: \p{Hang}) - (11_737) + (11_739) X \p{Hangul_Compatibility_Jamo} \p{Block=Hangul_Compatibility_Jamo} (96) X \p{Hangul_Jamo} \p{Block=Hangul_Jamo} (256) @@ -1455,7 +1504,7 @@ this property. (95) \p{Hangul_Syllable_Type: Vowel_Jamo} (Short: \p{Hst=V}) (95) X \p{Hangul_Syllables} \p{Block=Hangul_Syllables} (11_184) - \p{Hani} \p{Han} (= \p{Script=Han}) (75_738) + \p{Hani} \p{Han} (= \p{Script=Han}) (75_960) \p{Hano} \p{Hanunoo} (= \p{Script=Hanunoo}) (NOT \p{Block=Hanunoo}) (21) \p{Hanunoo} \p{Script=Hanunoo} (Short: \p{Hano}; NOT @@ -1473,38 +1522,38 @@ this property. High_Private_Use_Surrogates} (128) X \p{High_Surrogates} \p{Block=High_Surrogates} (896) \p{Hira} \p{Hiragana} (= \p{Script=Hiragana}) (NOT - \p{Block=Hiragana}) (90) + \p{Block=Hiragana}) (91) \p{Hiragana} \p{Script=Hiragana} (Short: \p{Hira}; NOT - \p{Block=Hiragana}) (90) + \p{Block=Hiragana}) (91) \p{HorizSpace} \p{Blank} (19) \p{Hst: *} \p{Hangul_Syllable_Type: *} - S \p{Hyphen} \p{Hyphen=Y} (11) - S \p{Hyphen: N*} Use the Line_Break property instead; see - www.unicode.org/reports/tr14 (Single: - \P{Hyphen}) (1_114_101) - S \p{Hyphen: Y*} Use the Line_Break property instead; see - www.unicode.org/reports/tr14 (Single: - \p{Hyphen}) (11) + D \p{Hyphen} \p{Hyphen=Y} (11) + D \p{Hyphen: N*} Supplanted by Line_Break property values; + see www.unicode.org/reports/tr14 + (Single: \P{Hyphen}) (1_114_101) + D \p{Hyphen: Y*} Supplanted by Line_Break property values; + see www.unicode.org/reports/tr14 + (Single: \p{Hyphen}) (11) \p{ID_Continue} \p{ID_Continue=Y} (Short: \p{IDC}) - (101_634) - \p{ID_Continue: N*} (Short: \p{IDC=N}, \P{IDC}) (1_012_478) - \p{ID_Continue: Y*} (Short: \p{IDC=Y}, \p{IDC}) (101_634) - \p{ID_Start} \p{ID_Start=Y} (Short: \p{IDS}) (99_764) - \p{ID_Start: N*} (Short: \p{IDS=N}, \P{IDS}) (1_014_348) - \p{ID_Start: Y*} (Short: \p{IDS=Y}, \p{IDS}) (99_764) + (102_675) + \p{ID_Continue: N*} (Short: \p{IDC=N}, \P{IDC}) (1_011_437) + \p{ID_Continue: Y*} (Short: \p{IDC=Y}, \p{IDC}) (102_675) + \p{ID_Start} \p{ID_Start=Y} (Short: \p{IDS}) (100_747) + \p{ID_Start: N*} (Short: \p{IDS=N}, \P{IDS}) (1_013_365) + \p{ID_Start: Y*} (Short: \p{IDS=Y}, \p{IDS}) (100_747) \p{IDC} \p{ID_Continue} (= \p{ID_Continue=Y}) - (101_634) + (102_675) \p{IDC: *} \p{ID_Continue: *} \p{Ideo} \p{Ideographic} (= \p{Ideographic=Y}) - (75_408) + (75_630) \p{Ideo: *} \p{Ideographic: *} \p{Ideographic} \p{Ideographic=Y} (Short: \p{Ideo}) - (75_408) - \p{Ideographic: N*} (Short: \p{Ideo=N}, \P{Ideo}) (1_038_704) - \p{Ideographic: Y*} (Short: \p{Ideo=Y}, \p{Ideo}) (75_408) + (75_630) + \p{Ideographic: N*} (Short: \p{Ideo=N}, \P{Ideo}) (1_038_482) + \p{Ideographic: Y*} (Short: \p{Ideo=Y}, \p{Ideo}) (75_630) X \p{Ideographic_Description_Characters} \p{Block= Ideographic_Description_Characters} (16) - \p{IDS} \p{ID_Start} (= \p{ID_Start=Y}) (99_764) + \p{IDS} \p{ID_Start} (= \p{ID_Start=Y}) (100_747) \p{IDS: *} \p{ID_Start: *} \p{IDS_Binary_Operator} \p{IDS_Binary_Operator=Y} (Short: \p{IDSB}) (10) @@ -1572,8 +1621,8 @@ this property. \p{Joining_Group: Gaf} (Short: \p{Jg=Gaf}) (13) \p{Joining_Group: Gamal} (Short: \p{Jg=Gamal}) (3) \p{Joining_Group: Hah} (Short: \p{Jg=Hah}) (17) - \p{Joining_Group: Hamza_On_Heh_Goal} (Short: \p{Jg= - HamzaOnHehGoal}) (1) + \p{Joining_Group: Hamza_On_Heh_Goal} \p{Joining_Group= + Teh_Marbuta_Goal} (1) \p{Joining_Group: He} (Short: \p{Jg=He}) (1) \p{Joining_Group: Heh} (Short: \p{Jg=Heh}) (1) \p{Joining_Group: Heh_Goal} (Short: \p{Jg=HehGoal}) (2) @@ -1587,7 +1636,7 @@ this property. \p{Joining_Group: Meem} (Short: \p{Jg=Meem}) (3) \p{Joining_Group: Mim} (Short: \p{Jg=Mim}) (1) \p{Joining_Group: No_Joining_Group} (Short: \p{Jg=NoJoiningGroup}) - (1_113_883) + (1_113_882) \p{Joining_Group: Noon} (Short: \p{Jg=Noon}) (8) \p{Joining_Group: Nun} (Short: \p{Jg=Nun}) (1) \p{Joining_Group: Nya} (Short: \p{Jg=Nya}) (1) @@ -1606,9 +1655,11 @@ this property. \p{Joining_Group: Tah} (Short: \p{Jg=Tah}) (3) \p{Joining_Group: Taw} (Short: \p{Jg=Taw}) (1) \p{Joining_Group: Teh_Marbuta} (Short: \p{Jg=TehMarbuta}) (3) + \p{Joining_Group: Teh_Marbuta_Goal} (Short: \p{Jg=TehMarbutaGoal}) + (1) \p{Joining_Group: Teth} (Short: \p{Jg=Teth}) (2) \p{Joining_Group: Waw} (Short: \p{Jg=Waw}) (15) - \p{Joining_Group: Yeh} (Short: \p{Jg=Yeh}) (7) + \p{Joining_Group: Yeh} (Short: \p{Jg=Yeh}) (8) \p{Joining_Group: Yeh_Barree} (Short: \p{Jg=YehBarree}) (2) \p{Joining_Group: Yeh_With_Tail} (Short: \p{Jg=YehWithTail}) (1) \p{Joining_Group: Yudh} (Short: \p{Jg=Yudh}) (1) @@ -1616,29 +1667,30 @@ this property. \p{Joining_Group: Zain} (Short: \p{Jg=Zain}) (1) \p{Joining_Group: Zhain} (Short: \p{Jg=Zhain}) (1) \p{Joining_Type: C} \p{Joining_Type=Join_Causing} (3) - \p{Joining_Type: D} \p{Joining_Type=Dual_Joining} (188) - \p{Joining_Type: Dual_Joining} (Short: \p{Jt=D}) (188) + \p{Joining_Type: D} \p{Joining_Type=Dual_Joining} (189) + \p{Joining_Type: Dual_Joining} (Short: \p{Jt=D}) (189) \p{Joining_Type: Join_Causing} (Short: \p{Jt=C}) (3) \p{Joining_Type: L} \p{Joining_Type=Left_Joining} (0) \p{Joining_Type: Left_Joining} (Short: \p{Jt=L}) (0) - \p{Joining_Type: Non_Joining} (Short: \p{Jt=U}) (1_112_539) + \p{Joining_Type: Non_Joining} (Short: \p{Jt=U}) (1_112_502) \p{Joining_Type: R} \p{Joining_Type=Right_Joining} (74) \p{Joining_Type: Right_Joining} (Short: \p{Jt=R}) (74) - \p{Joining_Type: T} \p{Joining_Type=Transparent} (1308) - \p{Joining_Type: Transparent} (Short: \p{Jt=T}) (1308) - \p{Joining_Type: U} \p{Joining_Type=Non_Joining} (1_112_539) + \p{Joining_Type: T} \p{Joining_Type=Transparent} (1344) + \p{Joining_Type: Transparent} (Short: \p{Jt=T}) (1344) + \p{Joining_Type: U} \p{Joining_Type=Non_Joining} (1_112_502) \p{Jt: *} \p{Joining_Type: *} \p{Kaithi} \p{Script=Kaithi} (Short: \p{Kthi}; NOT \p{Block=Kaithi}) (66) \p{Kali} \p{Kayah_Li} (= \p{Script=Kayah_Li}) (48) \p{Kana} \p{Katakana} (= \p{Script=Katakana}) (NOT - \p{Block=Katakana}) (299) + \p{Block=Katakana}) (300) + X \p{Kana_Supplement} \p{Block=Kana_Supplement} (256) X \p{Kanbun} \p{Block=Kanbun} (16) X \p{Kangxi_Radicals} \p{Block=Kangxi_Radicals} (224) \p{Kannada} \p{Script=Kannada} (Short: \p{Knda}; NOT - \p{Block=Kannada}) (84) + \p{Block=Kannada}) (86) \p{Katakana} \p{Script=Katakana} (Short: \p{Kana}; NOT - \p{Block=Katakana}) (299) + \p{Block=Katakana}) (300) X \p{Katakana_Phonetic_Extensions} \p{Block= Katakana_Phonetic_Extensions} (16) \p{Kayah_Li} \p{Script=Kayah_Li} (Short: \p{Kali}) (48) @@ -1652,21 +1704,21 @@ this property. \p{Khmr} \p{Khmer} (= \p{Script=Khmer}) (NOT \p{Block=Khmer}) (146) \p{Knda} \p{Kannada} (= \p{Script=Kannada}) (NOT - \p{Block=Kannada}) (84) + \p{Block=Kannada}) (86) \p{Kthi} \p{Kaithi} (= \p{Script=Kaithi}) (NOT \p{Block=Kaithi}) (66) \p{L} \p{Letter} (= \p{General_Category=Letter}) - (99_537) + (100_520) \p{L&} \p{Cased_Letter} (= \p{General_Category= - Cased_Letter}) (3207) + Cased_Letter}) (3226) \p{L_} \p{Cased_Letter} (= \p{General_Category= - Cased_Letter}) (3207) + Cased_Letter}) (3226) \p{Lana} \p{Tai_Tham} (= \p{Script=Tai_Tham}) (NOT \p{Block=Tai_Tham}) (127) \p{Lao} \p{Script=Lao} (NOT \p{Block=Lao}) (65) \p{Laoo} \p{Lao} (= \p{Script=Lao}) (NOT \p{Block= Lao}) (65) - \p{Latin} \p{Script=Latin} (Short: \p{Latn}) (1244) + \p{Latin} \p{Script=Latin} (Short: \p{Latn}) (1267) X \p{Latin_1} \p{Latin_1_Supplement} (= \p{Block= Latin_1_Supplement}) (128) X \p{Latin_1_Supplement} \p{Block=Latin_1_Supplement} (Short: @@ -1677,16 +1729,16 @@ this property. X \p{Latin_Extended_B} \p{Block=Latin_Extended_B} (208) X \p{Latin_Extended_C} \p{Block=Latin_Extended_C} (32) X \p{Latin_Extended_D} \p{Block=Latin_Extended_D} (224) - \p{Latn} \p{Latin} (= \p{Script=Latin}) (1244) + \p{Latn} \p{Latin} (= \p{Script=Latin}) (1267) \p{Lb: *} \p{Line_Break: *} \p{LC} \p{Cased_Letter} (= \p{General_Category= - Cased_Letter}) (3207) + Cased_Letter}) (3226) \p{Lepc} \p{Lepcha} (= \p{Script=Lepcha}) (NOT \p{Block=Lepcha}) (74) \p{Lepcha} \p{Script=Lepcha} (Short: \p{Lepc}; NOT \p{Block=Lepcha}) (74) \p{Letter} \p{General_Category=Letter} (Short: \p{L}) - (99_537) + (100_520) \p{Letter_Number} \p{General_Category=Letter_Number} (Short: \p{Nl}) (224) X \p{Letterlike_Symbols} \p{Block=Letterlike_Symbols} (80) @@ -1695,15 +1747,15 @@ this property. \p{Limbu} \p{Script=Limbu} (Short: \p{Limb}; NOT \p{Block=Limbu}) (66) \p{Linb} \p{Linear_B} (= \p{Script=Linear_B}) (211) - \p{Line_Break: AI} \p{Line_Break=Ambiguous} (644) - \p{Line_Break: AL} \p{Line_Break=Alphabetic} (14_092) - \p{Line_Break: Alphabetic} (Short: \p{Lb=AL}) (14_092) - \p{Line_Break: Ambiguous} (Short: \p{Lb=AI}) (644) + \p{Line_Break: AI} \p{Line_Break=Ambiguous} (724) + \p{Line_Break: AL} \p{Line_Break=Alphabetic} (15_797) + \p{Line_Break: Alphabetic} (Short: \p{Lb=AL}) (15_797) + \p{Line_Break: Ambiguous} (Short: \p{Lb=AI}) (724) \p{Line_Break: B2} \p{Line_Break=Break_Both} (1) - \p{Line_Break: BA} \p{Line_Break=Break_After} (137) + \p{Line_Break: BA} \p{Line_Break=Break_After} (140) \p{Line_Break: BB} \p{Line_Break=Break_Before} (19) \p{Line_Break: BK} \p{Line_Break=Mandatory_Break} (4) - \p{Line_Break: Break_After} (Short: \p{Lb=BA}) (137) + \p{Line_Break: Break_After} (Short: \p{Lb=BA}) (140) \p{Line_Break: Break_Before} (Short: \p{Lb=BB}) (19) \p{Line_Break: Break_Both} (Short: \p{Lb=B2}) (1) \p{Line_Break: Break_Symbols} (Short: \p{Lb=SY}) (1) @@ -1712,22 +1764,22 @@ this property. \p{Line_Break: CL} \p{Line_Break=Close_Punctuation} (87) \p{Line_Break: Close_Parenthesis} (Short: \p{Lb=CP}) (2) \p{Line_Break: Close_Punctuation} (Short: \p{Lb=CL}) (87) - \p{Line_Break: CM} \p{Line_Break=Combining_Mark} (1436) - \p{Line_Break: Combining_Mark} (Short: \p{Lb=CM}) (1436) - \p{Line_Break: Complex_Context} (Short: \p{Lb=SA}) (662) + \p{Line_Break: CM} \p{Line_Break=Combining_Mark} (1483) + \p{Line_Break: Combining_Mark} (Short: \p{Lb=CM}) (1483) + \p{Line_Break: Complex_Context} (Short: \p{Lb=SA}) (663) \p{Line_Break: Contingent_Break} (Short: \p{Lb=CB}) (1) \p{Line_Break: CP} \p{Line_Break=Close_Parenthesis} (2) \p{Line_Break: CR} \p{Line_Break=Carriage_Return} (1) \p{Line_Break: EX} \p{Line_Break=Exclamation} (34) \p{Line_Break: Exclamation} (Short: \p{Lb=EX}) (34) - \p{Line_Break: GL} \p{Line_Break=Glue} (16) - \p{Line_Break: Glue} (Short: \p{Lb=GL}) (16) + \p{Line_Break: GL} \p{Line_Break=Glue} (18) + \p{Line_Break: Glue} (Short: \p{Lb=GL}) (18) \p{Line_Break: H2} (Short: \p{Lb=H2}) (399) \p{Line_Break: H3} (Short: \p{Lb=H3}) (10_773) \p{Line_Break: HY} \p{Line_Break=Hyphen} (1) \p{Line_Break: Hyphen} (Short: \p{Lb=HY}) (1) - \p{Line_Break: ID} \p{Line_Break=Ideographic} (161_775) - \p{Line_Break: Ideographic} (Short: \p{Lb=ID}) (161_775) + \p{Line_Break: ID} \p{Line_Break=Ideographic} (161_793) + \p{Line_Break: Ideographic} (Short: \p{Lb=ID}) (161_793) \p{Line_Break: IN} \p{Line_Break=Inseparable} (4) \p{Line_Break: Infix_Numeric} (Short: \p{Lb=IS}) (13) \p{Line_Break: Inseparable} (Short: \p{Lb=IN}) (4) @@ -1743,17 +1795,17 @@ this property. \p{Line_Break: NL} \p{Line_Break=Next_Line} (1) \p{Line_Break: Nonstarter} (Short: \p{Lb=NS}) (77) \p{Line_Break: NS} \p{Line_Break=Nonstarter} (77) - \p{Line_Break: NU} \p{Line_Break=Numeric} (403) - \p{Line_Break: Numeric} (Short: \p{Lb=NU}) (403) + \p{Line_Break: NU} \p{Line_Break=Numeric} (412) + \p{Line_Break: Numeric} (Short: \p{Lb=NU}) (412) \p{Line_Break: OP} \p{Line_Break=Open_Punctuation} (81) \p{Line_Break: Open_Punctuation} (Short: \p{Lb=OP}) (81) \p{Line_Break: PO} \p{Line_Break=Postfix_Numeric} (28) \p{Line_Break: Postfix_Numeric} (Short: \p{Lb=PO}) (28) - \p{Line_Break: PR} \p{Line_Break=Prefix_Numeric} (43) - \p{Line_Break: Prefix_Numeric} (Short: \p{Lb=PR}) (43) + \p{Line_Break: PR} \p{Line_Break=Prefix_Numeric} (44) + \p{Line_Break: Prefix_Numeric} (Short: \p{Lb=PR}) (44) \p{Line_Break: QU} \p{Line_Break=Quotation} (34) \p{Line_Break: Quotation} (Short: \p{Lb=QU}) (34) - \p{Line_Break: SA} \p{Line_Break=Complex_Context} (662) + \p{Line_Break: SA} \p{Line_Break=Complex_Context} (663) D \p{Line_Break: SG} \p{Line_Break=Surrogate} (2048) \p{Line_Break: SP} \p{Line_Break=Space} (1) \p{Line_Break: Space} (Short: \p{Lb=SP}) (1) @@ -1762,10 +1814,10 @@ this property. and therefore shouldn't be the basis for line breaking (Short: \p{Lb=SG}) (2048) \p{Line_Break: SY} \p{Line_Break=Break_Symbols} (1) - \p{Line_Break: Unknown} (Short: \p{Lb=XX}) (920_933) + \p{Line_Break: Unknown} (Short: \p{Lb=XX}) (919_067) \p{Line_Break: WJ} \p{Line_Break=Word_Joiner} (2) \p{Line_Break: Word_Joiner} (Short: \p{Lb=WJ}) (2) - \p{Line_Break: XX} \p{Line_Break=Unknown} (920_933) + \p{Line_Break: XX} \p{Line_Break=Unknown} (919_067) \p{Line_Break: ZW} \p{Line_Break=ZWSpace} (1) \p{Line_Break: ZWSpace} (Short: \p{Lb=ZW}) (1) \p{Line_Separator} \p{General_Category=Line_Separator} @@ -1776,12 +1828,13 @@ this property. \p{Lisu} \p{Script=Lisu} (48) \p{Ll} \p{Lowercase_Letter} (= \p{General_Category=Lowercase_Letter}) - (1749) + (/i= General_Category=Cased_Letter) + (1759) \p{Lm} \p{Modifier_Letter} (= \p{General_Category=Modifier_Letter}) - (202) + (210) \p{Lo} \p{Other_Letter} (= \p{General_Category= - Other_Letter}) (96_128) + Other_Letter}) (97_084) \p{LOE} \p{Logical_Order_Exception} (= \p{Logical_Order_Exception=Y}) (15) \p{LOE: *} \p{Logical_Order_Exception: *} @@ -1791,18 +1844,24 @@ this property. (1_114_097) \p{Logical_Order_Exception: Y*} (Short: \p{LOE=Y}, \p{LOE}) (15) X \p{Low_Surrogates} \p{Block=Low_Surrogates} (1024) - \p{Lower} \p{Lowercase=Y} (1908) + \p{Lower} \p{Lowercase=Y} (/i= Cased=Yes) (1918) \p{Lower: *} \p{Lowercase: *} - \p{Lowercase} \p{Lower} (= \p{Lowercase=Y}) (1908) - \p{Lowercase: N*} (Short: \p{Lower=N}, \P{Lower}) (1_112_204) - \p{Lowercase: Y*} (Short: \p{Lower=Y}, \p{Lower}) (1908) + \p{Lowercase} \p{Lower} (= \p{Lowercase=Y}) (/i= Cased= + Yes) (1918) + \p{Lowercase: N*} (Short: \p{Lower=N}, \P{Lower}; /i= Cased= + No) (1_112_194) + \p{Lowercase: Y*} (Short: \p{Lower=Y}, \p{Lower}; /i= Cased= + Yes) (1918) \p{Lowercase_Letter} \p{General_Category=Lowercase_Letter} - (Short: \p{Ll}) (1749) - \p{Lt} \p{Title} (= \p{General_Category= - Titlecase_Letter}) (31) + (Short: \p{Ll}; /i= General_Category= + Cased_Letter) (1759) + \p{Lt} \p{Titlecase_Letter} (= + \p{General_Category=Titlecase_Letter}) + (/i= General_Category=Cased_Letter) (31) \p{Lu} \p{Uppercase_Letter} (= \p{General_Category=Uppercase_Letter}) - (1427) + (/i= General_Category=Cased_Letter) + (1436) \p{Lyci} \p{Lycian} (= \p{Script=Lycian}) (NOT \p{Block=Lycian}) (29) \p{Lycian} \p{Script=Lycian} (Short: \p{Lyci}; NOT @@ -1812,24 +1871,28 @@ this property. \p{Lydian} \p{Script=Lydian} (Short: \p{Lydi}; NOT \p{Block=Lydian}) (27) \p{M} \p{Mark} (= \p{General_Category=Mark}) - (1451) + (1498) X \p{Mahjong_Tiles} \p{Block=Mahjong_Tiles} (48) \p{Malayalam} \p{Script=Malayalam} (Short: \p{Mlym}; NOT - \p{Block=Malayalam}) (95) + \p{Block=Malayalam}) (98) + \p{Mand} \p{Mandaic} (= \p{Script=Mandaic}) (NOT + \p{Block=Mandaic}) (29) + \p{Mandaic} \p{Script=Mandaic} (Short: \p{Mand}; NOT + \p{Block=Mandaic}) (29) \p{Mark} \p{General_Category=Mark} (Short: \p{M}) - (1451) - \p{Math} \p{Math=Y} (2161) - \p{Math: N*} (Single: \P{Math}) (1_111_951) - \p{Math: Y*} (Single: \p{Math}) (2161) + (1498) + \p{Math} \p{Math=Y} (2165) + \p{Math: N*} (Single: \P{Math}) (1_111_947) + \p{Math: Y*} (Single: \p{Math}) (2165) \p{Math_Symbol} \p{General_Category=Math_Symbol} (Short: - \p{Sm}) (945) + \p{Sm}) (948) X \p{Mathematical_Alphanumeric_Symbols} \p{Block= Mathematical_Alphanumeric_Symbols} (1024) X \p{Mathematical_Operators} \p{Block=Mathematical_Operators} (256) \p{Mc} \p{Spacing_Mark} (= \p{General_Category= - Spacing_Mark}) (276) + Spacing_Mark}) (287) \p{Me} \p{Enclosing_Mark} (= \p{General_Category= - Enclosing_Mark}) (13) + Enclosing_Mark}) (12) \p{Meetei_Mayek} \p{Script=Meetei_Mayek} (Short: \p{Mtei}; NOT \p{Block=Meetei_Mayek}) (56) X \p{Miscellaneous_Mathematical_Symbols_A} \p{Block= @@ -1841,16 +1904,19 @@ this property. X \p{Miscellaneous_Symbols} \p{Block=Miscellaneous_Symbols} (256) X \p{Miscellaneous_Symbols_And_Arrows} \p{Block= Miscellaneous_Symbols_And_Arrows} (256) + X \p{Miscellaneous_Symbols_And_Pictographs} \p{Block= + Miscellaneous_Symbols_And_Pictographs} + (768) X \p{Miscellaneous_Technical} \p{Block=Miscellaneous_Technical} (256) \p{Mlym} \p{Malayalam} (= \p{Script=Malayalam}) - (NOT \p{Block=Malayalam}) (95) + (NOT \p{Block=Malayalam}) (98) \p{Mn} \p{Nonspacing_Mark} (= \p{General_Category=Nonspacing_Mark}) - (1162) + (1199) \p{Modifier_Letter} \p{General_Category=Modifier_Letter} - (Short: \p{Lm}) (202) + (Short: \p{Lm}) (210) \p{Modifier_Symbol} \p{General_Category=Modifier_Symbol} - (Short: \p{Sk}) (99) + (Short: \p{Sk}) (115) X \p{Modifier_Tone_Letters} \p{Block=Modifier_Tone_Letters} (32) \p{Mong} \p{Mongolian} (= \p{Script=Mongolian}) (NOT \p{Block=Mongolian}) (153) @@ -1866,12 +1932,12 @@ this property. \p{Mymr} \p{Myanmar} (= \p{Script=Myanmar}) (NOT \p{Block=Myanmar}) (188) \p{N} \p{Number} (= \p{General_Category=Number}) - (1064) + (1100) \p{NChar} \p{Noncharacter_Code_Point} (= \p{Noncharacter_Code_Point=Y}) (66) \p{NChar: *} \p{Noncharacter_Code_Point: *} \p{Nd} \p{Digit} (= \p{General_Category= - Decimal_Number}) (411) + Decimal_Number}) (420) \p{New_Tai_Lue} \p{Script=New_Tai_Lue} (Short: \p{Talu}; NOT \p{Block=New_Tai_Lue}) (83) \p{NFC_QC: *} \p{NFC_Quick_Check: *} @@ -1916,44 +1982,44 @@ this property. \p{NFKC_Quick_Check: N} \p{NFKC_Quick_Check=No} (NOT \P{NFKC_Quick_Check} NOR \P{NFKC_QC} NOR \P{Is_NFKC_Quick_Check} NOR - \P{Is_NFKC_QC}) (4597) + \P{Is_NFKC_QC}) (4640) \p{NFKC_Quick_Check: No} (Short: \p{NFKCQC=N}; NOT \P{NFKC_Quick_Check} NOR \P{NFKC_QC} NOR \P{Is_NFKC_Quick_Check} NOR - \P{Is_NFKC_QC}) (4597) + \P{Is_NFKC_QC}) (4640) \p{NFKC_Quick_Check: Y} \p{NFKC_Quick_Check=Yes} (NOT \p{NFKC_Quick_Check} NOR \p{NFKC_QC} NOR \p{Is_NFKC_Quick_Check} NOR - \p{Is_NFKC_QC}) (1_109_412) + \p{Is_NFKC_QC}) (1_109_369) \p{NFKC_Quick_Check: Yes} (Short: \p{NFKCQC=Y}; NOT \p{NFKC_Quick_Check} NOR \p{NFKC_QC} NOR \p{Is_NFKC_Quick_Check} NOR - \p{Is_NFKC_QC}) (1_109_412) + \p{Is_NFKC_QC}) (1_109_369) \p{NFKD_QC: *} \p{NFKD_Quick_Check: *} \p{NFKD_Quick_Check: N} \p{NFKD_Quick_Check=No} (NOT \P{NFKD_Quick_Check} NOR \P{NFKD_QC} NOR \P{Is_NFKD_Quick_Check} NOR - \P{Is_NFKD_QC}) (16_688) + \P{Is_NFKD_QC}) (16_731) \p{NFKD_Quick_Check: No} (Short: \p{NFKDQC=N}; NOT \P{NFKD_Quick_Check} NOR \P{NFKD_QC} NOR \P{Is_NFKD_Quick_Check} NOR - \P{Is_NFKD_QC}) (16_688) + \P{Is_NFKD_QC}) (16_731) \p{NFKD_Quick_Check: Y} \p{NFKD_Quick_Check=Yes} (NOT \p{NFKD_Quick_Check} NOR \p{NFKD_QC} NOR \p{Is_NFKD_Quick_Check} NOR - \p{Is_NFKD_QC}) (1_097_424) + \p{Is_NFKD_QC}) (1_097_381) \p{NFKD_Quick_Check: Yes} (Short: \p{NFKDQC=Y}; NOT \p{NFKD_Quick_Check} NOR \p{NFKD_QC} NOR \p{Is_NFKD_Quick_Check} NOR - \p{Is_NFKD_QC}) (1_097_424) + \p{Is_NFKD_QC}) (1_097_381) \p{Nko} \p{Script=Nko} (NOT \p{NKo}) (59) \p{Nkoo} \p{Nko} (= \p{Script=Nko}) (NOT \p{NKo}) (59) \p{Nl} \p{Letter_Number} (= \p{General_Category= Letter_Number}) (224) \p{No} \p{Other_Number} (= \p{General_Category= - Other_Number}) (429) - X \p{No_Block} \p{Block=No_Block} (864_192) + Other_Number}) (456) + X \p{No_Block} \p{Block=No_Block} (861_664) \p{Noncharacter_Code_Point} \p{Noncharacter_Code_Point=Y} (Short: \p{NChar}) (66) \p{Noncharacter_Code_Point: N*} (Short: \p{NChar=N}, \P{NChar}) @@ -1961,58 +2027,58 @@ this property. \p{Noncharacter_Code_Point: Y*} (Short: \p{NChar=Y}, \p{NChar}) (66) \p{Nonspacing_Mark} \p{General_Category=Nonspacing_Mark} - (Short: \p{Mn}) (1162) + (Short: \p{Mn}) (1199) \p{Nt: *} \p{Numeric_Type: *} \p{Number} \p{General_Category=Number} (Short: \p{N}) - (1064) + (1100) X \p{Number_Forms} \p{Block=Number_Forms} (64) - \p{Numeric_Type: De} \p{Numeric_Type=Decimal} (411) - \p{Numeric_Type: Decimal} (Short: \p{Nt=De}) (411) - \p{Numeric_Type: Di} \p{Numeric_Type=Digit} (118) - \p{Numeric_Type: Digit} (Short: \p{Nt=Di}) (118) - \p{Numeric_Type: None} (Short: \p{Nt=None}) (1_112_971) - \p{Numeric_Type: Nu} \p{Numeric_Type=Numeric} (612) - \p{Numeric_Type: Numeric} (Short: \p{Nt=Nu}) (612) + \p{Numeric_Type: De} \p{Numeric_Type=Decimal} (420) + \p{Numeric_Type: Decimal} (Short: \p{Nt=De}) (420) + \p{Numeric_Type: Di} \p{Numeric_Type=Digit} (128) + \p{Numeric_Type: Digit} (Short: \p{Nt=Di}) (128) + \p{Numeric_Type: None} (Short: \p{Nt=None}) (1_112_935) + \p{Numeric_Type: Nu} \p{Numeric_Type=Numeric} (629) + \p{Numeric_Type: Numeric} (Short: \p{Nt=Nu}) (629) T \p{Numeric_Value: -1/2} (Short: \p{Nv=-1/2}) (1) - T \p{Numeric_Value: 0} (Short: \p{Nv=0}) (55) - T \p{Numeric_Value: 1/16} (Short: \p{Nv=1/16}) (2) + T \p{Numeric_Value: 0} (Short: \p{Nv=0}) (56) + T \p{Numeric_Value: 1/16} (Short: \p{Nv=1/16}) (3) T \p{Numeric_Value: 1/10} (Short: \p{Nv=1/10}) (1) T \p{Numeric_Value: 1/9} (Short: \p{Nv=1/9}) (1) - T \p{Numeric_Value: 1/8} (Short: \p{Nv=1/8}) (4) + T \p{Numeric_Value: 1/8} (Short: \p{Nv=1/8}) (5) T \p{Numeric_Value: 1/7} (Short: \p{Nv=1/7}) (1) T \p{Numeric_Value: 1/6} (Short: \p{Nv=1/6}) (2) - T \p{Numeric_Value: 3/16} (Short: \p{Nv=3/16}) (2) + T \p{Numeric_Value: 3/16} (Short: \p{Nv=3/16}) (3) T \p{Numeric_Value: 1/5} (Short: \p{Nv=1/5}) (1) - T \p{Numeric_Value: 1/4} (Short: \p{Nv=1/4}) (8) + T \p{Numeric_Value: 1/4} (Short: \p{Nv=1/4}) (9) T \p{Numeric_Value: 1/3} (Short: \p{Nv=1/3}) (4) T \p{Numeric_Value: 3/8} (Short: \p{Nv=3/8}) (1) T \p{Numeric_Value: 2/5} (Short: \p{Nv=2/5}) (1) - T \p{Numeric_Value: 1/2} (Short: \p{Nv=1/2}) (9) + T \p{Numeric_Value: 1/2} (Short: \p{Nv=1/2}) (10) T \p{Numeric_Value: 3/5} (Short: \p{Nv=3/5}) (1) T \p{Numeric_Value: 5/8} (Short: \p{Nv=5/8}) (1) T \p{Numeric_Value: 2/3} (Short: \p{Nv=2/3}) (5) - T \p{Numeric_Value: 3/4} (Short: \p{Nv=3/4}) (5) + T \p{Numeric_Value: 3/4} (Short: \p{Nv=3/4}) (6) T \p{Numeric_Value: 4/5} (Short: \p{Nv=4/5}) (1) T \p{Numeric_Value: 5/6} (Short: \p{Nv=5/6}) (2) T \p{Numeric_Value: 7/8} (Short: \p{Nv=7/8}) (1) - T \p{Numeric_Value: 1} (Short: \p{Nv=1}) (91) + T \p{Numeric_Value: 1} (Short: \p{Nv=1}) (93) T \p{Numeric_Value: 3/2} (Short: \p{Nv=3/2}) (1) - T \p{Numeric_Value: 2} (Short: \p{Nv=2}) (94) + T \p{Numeric_Value: 2} (Short: \p{Nv=2}) (96) T \p{Numeric_Value: 5/2} (Short: \p{Nv=5/2}) (1) - T \p{Numeric_Value: 3} (Short: \p{Nv=3}) (96) + T \p{Numeric_Value: 3} (Short: \p{Nv=3}) (98) T \p{Numeric_Value: 7/2} (Short: \p{Nv=7/2}) (1) - T \p{Numeric_Value: 4} (Short: \p{Nv=4}) (87) + T \p{Numeric_Value: 4} (Short: \p{Nv=4}) (89) T \p{Numeric_Value: 9/2} (Short: \p{Nv=9/2}) (1) - T \p{Numeric_Value: 5} (Short: \p{Nv=5}) (84) + T \p{Numeric_Value: 5} (Short: \p{Nv=5}) (86) T \p{Numeric_Value: 11/2} (Short: \p{Nv=11/2}) (1) - T \p{Numeric_Value: 6} (Short: \p{Nv=6}) (76) + T \p{Numeric_Value: 6} (Short: \p{Nv=6}) (78) T \p{Numeric_Value: 13/2} (Short: \p{Nv=13/2}) (1) - T \p{Numeric_Value: 7} (Short: \p{Nv=7}) (75) + T \p{Numeric_Value: 7} (Short: \p{Nv=7}) (77) T \p{Numeric_Value: 15/2} (Short: \p{Nv=15/2}) (1) - T \p{Numeric_Value: 8} (Short: \p{Nv=8}) (71) + T \p{Numeric_Value: 8} (Short: \p{Nv=8}) (73) T \p{Numeric_Value: 17/2} (Short: \p{Nv=17/2}) (1) - T \p{Numeric_Value: 9} (Short: \p{Nv=9}) (75) - T \p{Numeric_Value: 10} (Short: \p{Nv=10}) (38) + T \p{Numeric_Value: 9} (Short: \p{Nv=9}) (77) + T \p{Numeric_Value: 10} (Short: \p{Nv=10}) (39) T \p{Numeric_Value: 11} (Short: \p{Nv=11}) (6) T \p{Numeric_Value: 12} (Short: \p{Nv=12}) (6) T \p{Numeric_Value: 13} (Short: \p{Nv=13}) (4) @@ -2022,7 +2088,7 @@ this property. T \p{Numeric_Value: 17} (Short: \p{Nv=17}) (5) T \p{Numeric_Value: 18} (Short: \p{Nv=18}) (5) T \p{Numeric_Value: 19} (Short: \p{Nv=19}) (5) - T \p{Numeric_Value: 20} (Short: \p{Nv=20}) (17) + T \p{Numeric_Value: 20} (Short: \p{Nv=20}) (18) T \p{Numeric_Value: 21} (Short: \p{Nv=21}) (1) T \p{Numeric_Value: 22} (Short: \p{Nv=22}) (1) T \p{Numeric_Value: 23} (Short: \p{Nv=23}) (1) @@ -2032,7 +2098,7 @@ this property. T \p{Numeric_Value: 27} (Short: \p{Nv=27}) (1) T \p{Numeric_Value: 28} (Short: \p{Nv=28}) (1) T \p{Numeric_Value: 29} (Short: \p{Nv=29}) (1) - T \p{Numeric_Value: 30} (Short: \p{Nv=30}) (9) + T \p{Numeric_Value: 30} (Short: \p{Nv=30}) (10) T \p{Numeric_Value: 31} (Short: \p{Nv=31}) (1) T \p{Numeric_Value: 32} (Short: \p{Nv=32}) (1) T \p{Numeric_Value: 33} (Short: \p{Nv=33}) (1) @@ -2042,7 +2108,7 @@ this property. T \p{Numeric_Value: 37} (Short: \p{Nv=37}) (1) T \p{Numeric_Value: 38} (Short: \p{Nv=38}) (1) T \p{Numeric_Value: 39} (Short: \p{Nv=39}) (1) - T \p{Numeric_Value: 40} (Short: \p{Nv=40}) (8) + T \p{Numeric_Value: 40} (Short: \p{Nv=40}) (9) T \p{Numeric_Value: 41} (Short: \p{Nv=41}) (1) T \p{Numeric_Value: 42} (Short: \p{Nv=42}) (1) T \p{Numeric_Value: 43} (Short: \p{Nv=43}) (1) @@ -2052,12 +2118,12 @@ this property. T \p{Numeric_Value: 47} (Short: \p{Nv=47}) (1) T \p{Numeric_Value: 48} (Short: \p{Nv=48}) (1) T \p{Numeric_Value: 49} (Short: \p{Nv=49}) (1) - T \p{Numeric_Value: 50} (Short: \p{Nv=50}) (18) - T \p{Numeric_Value: 60} (Short: \p{Nv=60}) (4) - T \p{Numeric_Value: 70} (Short: \p{Nv=70}) (4) - T \p{Numeric_Value: 80} (Short: \p{Nv=80}) (4) - T \p{Numeric_Value: 90} (Short: \p{Nv=90}) (5) - T \p{Numeric_Value: 100} (Short: \p{Nv=100}) (19) + T \p{Numeric_Value: 50} (Short: \p{Nv=50}) (19) + T \p{Numeric_Value: 60} (Short: \p{Nv=60}) (5) + T \p{Numeric_Value: 70} (Short: \p{Nv=70}) (5) + T \p{Numeric_Value: 80} (Short: \p{Nv=80}) (5) + T \p{Numeric_Value: 90} (Short: \p{Nv=90}) (6) + T \p{Numeric_Value: 100} (Short: \p{Nv=100}) (20) T \p{Numeric_Value: 200} (Short: \p{Nv=200}) (2) T \p{Numeric_Value: 300} (Short: \p{Nv=300}) (3) T \p{Numeric_Value: 400} (Short: \p{Nv=400}) (2) @@ -2066,7 +2132,7 @@ this property. T \p{Numeric_Value: 700} (Short: \p{Nv=700}) (2) T \p{Numeric_Value: 800} (Short: \p{Nv=800}) (2) T \p{Numeric_Value: 900} (Short: \p{Nv=900}) (3) - T \p{Numeric_Value: 1000} (Short: \p{Nv=1000}) (16) + T \p{Numeric_Value: 1000} (Short: \p{Nv=1000}) (17) T \p{Numeric_Value: 2000} (Short: \p{Nv=2000}) (1) T \p{Numeric_Value: 3000} (Short: \p{Nv=3000}) (1) T \p{Numeric_Value: 4000} (Short: \p{Nv=4000}) (1) @@ -2089,10 +2155,10 @@ this property. 100000000}) (2) T \p{Numeric_Value: 1000000000000} (= 1.0e+012) (Short: \p{Nv= 1000000000000}) (1) - \p{Numeric_Value: NaN} (Short: \p{Nv=NaN}) (1_112_971) + \p{Numeric_Value: NaN} (Short: \p{Nv=NaN}) (1_112_935) \p{Nv: *} \p{Numeric_Value: *} D \p{OAlpha} \p{Other_Alphabetic} (= - \p{Other_Alphabetic=Y}) (759) + \p{Other_Alphabetic=Y}) (795) D \p{OAlpha: *} \p{Other_Alphabetic: *} D \p{ODI} \p{Other_Default_Ignorable_Code_Point} (= \p{Other_Default_Ignorable_Code_Point= @@ -2106,7 +2172,7 @@ this property. \p{Other_Grapheme_Extend=Y}) (23) D \p{OGr_Ext: *} \p{Other_Grapheme_Extend: *} D \p{OIDC} \p{Other_ID_Continue} (= - \p{Other_ID_Continue=Y}) (11) + \p{Other_ID_Continue=Y}) (12) D \p{OIDC: *} \p{Other_ID_Continue: *} D \p{OIDS} \p{Other_ID_Start} (= \p{Other_ID_Start= Y}) (4) @@ -2124,36 +2190,36 @@ this property. D \p{OLower} \p{Other_Lowercase} (= \p{Other_Lowercase= Y}) (159) D \p{OLower: *} \p{Other_Lowercase: *} - D \p{OMath} \p{Other_Math} (= \p{Other_Math=Y}) (1216) + D \p{OMath} \p{Other_Math} (= \p{Other_Math=Y}) (1217) D \p{OMath: *} \p{Other_Math: *} \p{Open_Punctuation} \p{General_Category=Open_Punctuation} (Short: \p{Ps}) (72) X \p{Optical_Character_Recognition} \p{Block= Optical_Character_Recognition} (32) \p{Oriya} \p{Script=Oriya} (Short: \p{Orya}; NOT - \p{Block=Oriya}) (84) + \p{Block=Oriya}) (90) \p{Orkh} \p{Old_Turkic} (= \p{Script=Old_Turkic}) (NOT \p{Block=Old_Turkic}) (73) \p{Orya} \p{Oriya} (= \p{Script=Oriya}) (NOT - \p{Block=Oriya}) (84) + \p{Block=Oriya}) (90) \p{Osma} \p{Osmanya} (= \p{Script=Osmanya}) (NOT \p{Block=Osmanya}) (40) \p{Osmanya} \p{Script=Osmanya} (Short: \p{Osma}; NOT \p{Block=Osmanya}) (40) \p{Other} \p{General_Category=Other} (Short: \p{C}) - (1_006_956) + (1_004_868) D \p{Other_Alphabetic} \p{Other_Alphabetic=Y} (Short: \p{OAlpha}) - (759) + (795) D \p{Other_Alphabetic: N*} Used by Unicode internally for generating the Alphabetic property (which should be used instead) and not intended to be used stand-alone (Short: \p{OAlpha=N}, - \P{OAlpha}) (1_113_353) + \P{OAlpha}) (1_113_317) D \p{Other_Alphabetic: Y*} Used by Unicode internally for generating the Alphabetic property (which should be used instead) and not intended to be used stand-alone (Short: \p{OAlpha=Y}, - \p{OAlpha}) (759) + \p{OAlpha}) (795) D \p{Other_Default_Ignorable_Code_Point} \p{Other_Default_Ignorable_Code_Point=Y} (Short: \p{ODI}) (3778) @@ -2182,17 +2248,17 @@ this property. intended to be used stand-alone (Short: \p{OGrExt=Y}, \p{OGrExt}) (23) D \p{Other_ID_Continue} \p{Other_ID_Continue=Y} (Short: \p{OIDC}) - (11) + (12) D \p{Other_ID_Continue: N*} Used by Unicode internally for generating the ID_Continue property (which should be used instead) and not intended to be used stand-alone (Short: - \p{OIDC=N}, \P{OIDC}) (1_114_101) + \p{OIDC=N}, \P{OIDC}) (1_114_100) D \p{Other_ID_Continue: Y*} Used by Unicode internally for generating the ID_Continue property (which should be used instead) and not intended to be used stand-alone (Short: - \p{OIDC=Y}, \p{OIDC}) (11) + \p{OIDC=Y}, \p{OIDC}) (12) D \p{Other_ID_Start} \p{Other_ID_Start=Y} (Short: \p{OIDS}) (4) D \p{Other_ID_Start: N*} Used by Unicode internally for generating the ID_Start property (which should be @@ -2205,7 +2271,7 @@ this property. used stand-alone (Short: \p{OIDS=Y}, \p{OIDS}) (4) \p{Other_Letter} \p{General_Category=Other_Letter} (Short: - \p{Lo}) (96_128) + \p{Lo}) (97_084) D \p{Other_Lowercase} \p{Other_Lowercase=Y} (Short: \p{OLower}) (159) D \p{Other_Lowercase: N*} Used by Unicode internally for generating @@ -2218,23 +2284,23 @@ this property. used instead) and not intended to be used stand-alone (Short: \p{OLower=Y}, \p{OLower}) (159) - D \p{Other_Math} \p{Other_Math=Y} (Short: \p{OMath}) (1216) + D \p{Other_Math} \p{Other_Math=Y} (Short: \p{OMath}) (1217) D \p{Other_Math: N*} Used by Unicode internally for generating the Math property (which should be used instead) and not intended to be used stand-alone (Short: \p{OMath=N}, - \P{OMath}) (1_112_896) + \P{OMath}) (1_112_895) D \p{Other_Math: Y*} Used by Unicode internally for generating the Math property (which should be used instead) and not intended to be used stand-alone (Short: \p{OMath=Y}, - \p{OMath}) (1216) + \p{OMath}) (1217) \p{Other_Number} \p{General_Category=Other_Number} (Short: - \p{No}) (429) + \p{No}) (456) \p{Other_Punctuation} \p{General_Category=Other_Punctuation} - (Short: \p{Po}) (389) + (Short: \p{Po}) (402) \p{Other_Symbol} \p{General_Category=Other_Symbol} (Short: - \p{So}) (3409) + \p{So}) (4398) D \p{Other_Uppercase} \p{Other_Uppercase=Y} (Short: \p{OUpper}) (42) D \p{Other_Uppercase: N*} Used by Unicode internally for generating @@ -2251,7 +2317,7 @@ this property. Y}) (42) D \p{OUpper: *} \p{Other_Uppercase: *} \p{P} \p{Punct} (= \p{General_Category= - Punctuation}) (585) + Punctuation}) (598) \p{Paragraph_Separator} \p{General_Category=Paragraph_Separator} (Short: \p{Zp}) (1) \p{Pat_Syn} \p{Pattern_Syntax} (= \p{Pattern_Syntax= @@ -2302,22 +2368,30 @@ this property. \p{Pi} \p{Initial_Punctuation} (= \p{General_Category= Initial_Punctuation}) (12) + X \p{Playing_Cards} \p{Block=Playing_Cards} (96) \p{Po} \p{Other_Punctuation} (= \p{General_Category=Other_Punctuation}) - (389) + (402) \p{PosixAlnum} [A-Za-z0-9] (62) \p{PosixAlpha} [A-Za-z] (52) \p{PosixBlank} \t and ' ' (2) - \p{PosixCntrl} [\x00-\x1F] (33) + \p{PosixCntrl} ASCII control characters: NUL, SOH, STX, + ETX, EOT, ENQ, ACK, BEL, BS, HT, LF, VT, + FF, CR, SO, SI, DLE, DC1, DC2, DC3, DC4, + NAK, SYN, ETB, CAN, EOM, SUB, ESC, FS, + GS, RS, US, and DEL (33) \p{PosixDigit} [0-9] (10) - \p{PosixGraph} [\x21-\x7E] (94) - \p{PosixLower} [a-z] (26) - \p{PosixPrint} [\x20-\x7E] (95) - \p{PosixPunct} Graphical characters that aren't Word - characters = [\x21-\x2F\x3A-\x40\x5B- - \x60\x7B-\x7E] (32) - \p{PosixSpace} \t \n, \x0B, \f, \r, and ' ' (6) - \p{PosixUpper} [A-Z] (26) + \p{PosixGraph} [-!"#$%&'()*+,./:;<>?@[\\]^_`{|}~0-9A-Za- + z] (94) + \p{PosixLower} [a-z] (/i= PosixAlpha) (26) + \p{PosixPrint} [- 0-9A-Za- + z!"#$%&'()*+,./:;<>?@[\\]^_`{|}~] (95) + \p{PosixPunct} [-!"#$%&'()*+,./:;<>?@[\\]^_`{|}~] (32) + \p{PosixSpace} \t, \n, \cK, \f, \r, and ' '. (\cK is + vertical tab) (6) + \p{PosixUpper} [A-Z] (/i= PosixAlpha) (26) + \p{PosixWord} \p{PerlWord} (63) + \p{PosixXDigit} [0-9A-Fa-f] (22) T \p{Present_In: 1.1} \p{Age=1.1} (Short: \p{In=1.1}) (Perl extension) (33_979) T \p{Present_In: 2.0} Code point's usage introduced in version @@ -2350,10 +2424,13 @@ this property. T \p{Present_In: 5.2} Code point's usage introduced in version 5.2 or earlier (Short: \p{In=5.2}) (Perl extension) (246_943) + T \p{Present_In: 6.0} Code point's usage introduced in version + 6.0 or earlier (Short: \p{In=6.0}) (Perl + extension) (249_031) \p{Present_In: Unassigned} \p{Age=Unassigned} (Short: \p{In= - Unassigned}) (Perl extension) (867_169) + Unassigned}) (Perl extension) (865_081) \p{Print} Characters that are graphical plus space - characters (but no controls) (244_762) + characters (but no controls) (246_850) \p{Private_Use} \p{General_Category=Private_Use} (Short: \p{Co}; NOT \p{Private_Use_Area}) (137_468) @@ -2366,9 +2443,9 @@ this property. \p{General_Category=Open_Punctuation}) (72) \p{Punct} \p{General_Category=Punctuation} (Short: - \p{P}) (585) + \p{P}) (598) \p{Punctuation} \p{Punct} (= \p{General_Category= - Punctuation}) (585) + Punctuation}) (598) \p{Qaac} \p{Coptic} (= \p{Script=Coptic}) (NOT \p{Block=Coptic}) (135) \p{Qaai} \p{Inherited} (= \p{Script=Inherited}) @@ -2393,7 +2470,7 @@ this property. \p{Runr} \p{Runic} (= \p{Script=Runic}) (NOT \p{Block=Runic}) (78) \p{S} \p{Symbol} (= \p{General_Category=Symbol}) - (4499) + (5508) \p{Samaritan} \p{Script=Samaritan} (Short: \p{Samr}; NOT \p{Block=Samaritan}) (61) \p{Samr} \p{Samaritan} (= \p{Script=Samaritan}) @@ -2407,10 +2484,10 @@ this property. \p{SB: *} \p{Sentence_Break: *} \p{Sc} \p{Currency_Symbol} (= \p{General_Category=Currency_Symbol}) - (46) + (47) \p{Sc: *} \p{Script: *} - \p{Script: Arab} \p{Script=Arabic} (1030) - \p{Script: Arabic} (Short: \p{Sc=Arab}, \p{Arab}) (1030) + \p{Script: Arab} \p{Script=Arabic} (1051) + \p{Script: Arabic} (Short: \p{Sc=Arab}, \p{Arab}) (1051) \p{Script: Armenian} (Short: \p{Sc=Armn}, \p{Armn}) (90) \p{Script: Armi} \p{Script=Imperial_Aramaic} (31) \p{Script: Armn} \p{Script=Armenian} (90) @@ -2418,12 +2495,16 @@ this property. \p{Script: Avst} \p{Script=Avestan} (61) \p{Script: Bali} \p{Script=Balinese} (121) \p{Script: Balinese} (Short: \p{Sc=Bali}, \p{Bali}) (121) - \p{Script: Bamu} \p{Script=Bamum} (88) - \p{Script: Bamum} (Short: \p{Sc=Bamu}, \p{Bamu}) (88) + \p{Script: Bamu} \p{Script=Bamum} (657) + \p{Script: Bamum} (Short: \p{Sc=Bamu}, \p{Bamu}) (657) + \p{Script: Batak} (Short: \p{Sc=Batk}, \p{Batk}) (56) + \p{Script: Batk} \p{Script=Batak} (56) \p{Script: Beng} \p{Script=Bengali} (92) \p{Script: Bengali} (Short: \p{Sc=Beng}, \p{Beng}) (92) - \p{Script: Bopo} \p{Script=Bopomofo} (65) - \p{Script: Bopomofo} (Short: \p{Sc=Bopo}, \p{Bopo}) (65) + \p{Script: Bopo} \p{Script=Bopomofo} (70) + \p{Script: Bopomofo} (Short: \p{Sc=Bopo}, \p{Bopo}) (70) + \p{Script: Brah} \p{Script=Brahmi} (108) + \p{Script: Brahmi} (Short: \p{Sc=Brah}, \p{Brah}) (108) \p{Script: Brai} \p{Script=Braille} (256) \p{Script: Braille} (Short: \p{Sc=Brai}, \p{Brai}) (256) \p{Script: Bugi} \p{Script=Buginese} (30) @@ -2438,23 +2519,23 @@ this property. \p{Script: Cham} (Short: \p{Sc=Cham}, \p{Cham}) (83) \p{Script: Cher} \p{Script=Cherokee} (85) \p{Script: Cherokee} (Short: \p{Sc=Cher}, \p{Cher}) (85) - \p{Script: Common} (Short: \p{Sc=Zyyy}, \p{Zyyy}) (5395) + \p{Script: Common} (Short: \p{Sc=Zyyy}, \p{Zyyy}) (6379) \p{Script: Copt} \p{Script=Coptic} (135) \p{Script: Coptic} (Short: \p{Sc=Copt}, \p{Copt}) (135) \p{Script: Cprt} \p{Script=Cypriot} (55) \p{Script: Cuneiform} (Short: \p{Sc=Xsux}, \p{Xsux}) (982) \p{Script: Cypriot} (Short: \p{Sc=Cprt}, \p{Cprt}) (55) - \p{Script: Cyrillic} (Short: \p{Sc=Cyrl}, \p{Cyrl}) (404) - \p{Script: Cyrl} \p{Script=Cyrillic} (404) + \p{Script: Cyrillic} (Short: \p{Sc=Cyrl}, \p{Cyrl}) (408) + \p{Script: Cyrl} \p{Script=Cyrillic} (408) \p{Script: Deseret} (Short: \p{Sc=Dsrt}, \p{Dsrt}) (80) - \p{Script: Deva} \p{Script=Devanagari} (140) - \p{Script: Devanagari} (Short: \p{Sc=Deva}, \p{Deva}) (140) + \p{Script: Deva} \p{Script=Devanagari} (150) + \p{Script: Devanagari} (Short: \p{Sc=Deva}, \p{Deva}) (150) \p{Script: Dsrt} \p{Script=Deseret} (80) \p{Script: Egyp} \p{Script=Egyptian_Hieroglyphs} (1071) \p{Script: Egyptian_Hieroglyphs} (Short: \p{Sc=Egyp}, \p{Egyp}) (1071) - \p{Script: Ethi} \p{Script=Ethiopic} (461) - \p{Script: Ethiopic} (Short: \p{Sc=Ethi}, \p{Ethi}) (461) + \p{Script: Ethi} \p{Script=Ethiopic} (495) + \p{Script: Ethiopic} (Short: \p{Sc=Ethi}, \p{Ethi}) (495) \p{Script: Geor} \p{Script=Georgian} (120) \p{Script: Georgian} (Short: \p{Sc=Geor}, \p{Geor}) (120) \p{Script: Glag} \p{Script=Glagolitic} (94) @@ -2467,16 +2548,16 @@ this property. \p{Script: Gujr} \p{Script=Gujarati} (83) \p{Script: Gurmukhi} (Short: \p{Sc=Guru}, \p{Guru}) (79) \p{Script: Guru} \p{Script=Gurmukhi} (79) - \p{Script: Han} (Short: \p{Sc=Han}, \p{Han}) (75_738) - \p{Script: Hang} \p{Script=Hangul} (11_737) - \p{Script: Hangul} (Short: \p{Sc=Hang}, \p{Hang}) (11_737) - \p{Script: Hani} \p{Script=Han} (75_738) + \p{Script: Han} (Short: \p{Sc=Han}, \p{Han}) (75_960) + \p{Script: Hang} \p{Script=Hangul} (11_739) + \p{Script: Hangul} (Short: \p{Sc=Hang}, \p{Hang}) (11_739) + \p{Script: Hani} \p{Script=Han} (75_960) \p{Script: Hano} \p{Script=Hanunoo} (21) \p{Script: Hanunoo} (Short: \p{Sc=Hano}, \p{Hano}) (21) \p{Script: Hebr} \p{Script=Hebrew} (133) \p{Script: Hebrew} (Short: \p{Sc=Hebr}, \p{Hebr}) (133) - \p{Script: Hira} \p{Script=Hiragana} (90) - \p{Script: Hiragana} (Short: \p{Sc=Hira}, \p{Hira}) (90) + \p{Script: Hira} \p{Script=Hiragana} (91) + \p{Script: Hiragana} (Short: \p{Sc=Hira}, \p{Hira}) (91) \p{Script: Imperial_Aramaic} (Short: \p{Sc=Armi}, \p{Armi}) (31) \p{Script: Inherited} (Short: \p{Sc=Zinh}, \p{Zinh}) (523) \p{Script: Inscriptional_Pahlavi} (Short: \p{Sc=Phli}, \p{Phli}) @@ -2488,21 +2569,21 @@ this property. \p{Script: Javanese} (Short: \p{Sc=Java}, \p{Java}) (91) \p{Script: Kaithi} (Short: \p{Sc=Kthi}, \p{Kthi}) (66) \p{Script: Kali} \p{Script=Kayah_Li} (48) - \p{Script: Kana} \p{Script=Katakana} (299) - \p{Script: Kannada} (Short: \p{Sc=Knda}, \p{Knda}) (84) - \p{Script: Katakana} (Short: \p{Sc=Kana}, \p{Kana}) (299) + \p{Script: Kana} \p{Script=Katakana} (300) + \p{Script: Kannada} (Short: \p{Sc=Knda}, \p{Knda}) (86) + \p{Script: Katakana} (Short: \p{Sc=Kana}, \p{Kana}) (300) \p{Script: Kayah_Li} (Short: \p{Sc=Kali}, \p{Kali}) (48) \p{Script: Khar} \p{Script=Kharoshthi} (65) \p{Script: Kharoshthi} (Short: \p{Sc=Khar}, \p{Khar}) (65) \p{Script: Khmer} (Short: \p{Sc=Khmr}, \p{Khmr}) (146) \p{Script: Khmr} \p{Script=Khmer} (146) - \p{Script: Knda} \p{Script=Kannada} (84) + \p{Script: Knda} \p{Script=Kannada} (86) \p{Script: Kthi} \p{Script=Kaithi} (66) \p{Script: Lana} \p{Script=Tai_Tham} (127) \p{Script: Lao} (Short: \p{Sc=Lao}, \p{Lao}) (65) \p{Script: Laoo} \p{Script=Lao} (65) - \p{Script: Latin} (Short: \p{Sc=Latn}, \p{Latn}) (1244) - \p{Script: Latn} \p{Script=Latin} (1244) + \p{Script: Latin} (Short: \p{Sc=Latn}, \p{Latn}) (1267) + \p{Script: Latn} \p{Script=Latin} (1267) \p{Script: Lepc} \p{Script=Lepcha} (74) \p{Script: Lepcha} (Short: \p{Sc=Lepc}, \p{Lepc}) (74) \p{Script: Limb} \p{Script=Limbu} (66) @@ -2514,9 +2595,11 @@ this property. \p{Script: Lycian} (Short: \p{Sc=Lyci}, \p{Lyci}) (29) \p{Script: Lydi} \p{Script=Lydian} (27) \p{Script: Lydian} (Short: \p{Sc=Lydi}, \p{Lydi}) (27) - \p{Script: Malayalam} (Short: \p{Sc=Mlym}, \p{Mlym}) (95) + \p{Script: Malayalam} (Short: \p{Sc=Mlym}, \p{Mlym}) (98) + \p{Script: Mand} \p{Script=Mandaic} (29) + \p{Script: Mandaic} (Short: \p{Sc=Mand}, \p{Mand}) (29) \p{Script: Meetei_Mayek} (Short: \p{Sc=Mtei}, \p{Mtei}) (56) - \p{Script: Mlym} \p{Script=Malayalam} (95) + \p{Script: Mlym} \p{Script=Malayalam} (98) \p{Script: Mong} \p{Script=Mongolian} (153) \p{Script: Mongolian} (Short: \p{Sc=Mong}, \p{Mong}) (153) \p{Script: Mtei} \p{Script=Meetei_Mayek} (56) @@ -2533,9 +2616,9 @@ this property. \p{Script: Old_Persian} (Short: \p{Sc=Xpeo}, \p{Xpeo}) (50) \p{Script: Old_South_Arabian} (Short: \p{Sc=Sarb}, \p{Sarb}) (32) \p{Script: Old_Turkic} (Short: \p{Sc=Orkh}, \p{Orkh}) (73) - \p{Script: Oriya} (Short: \p{Sc=Orya}, \p{Orya}) (84) + \p{Script: Oriya} (Short: \p{Sc=Orya}, \p{Orya}) (90) \p{Script: Orkh} \p{Script=Old_Turkic} (73) - \p{Script: Orya} \p{Script=Oriya} (84) + \p{Script: Orya} \p{Script=Oriya} (90) \p{Script: Osma} \p{Script=Osmanya} (40) \p{Script: Osmanya} (Short: \p{Sc=Osma}, \p{Osma}) (40) \p{Script: Phag} \p{Script=Phags_Pa} (56) @@ -2578,17 +2661,17 @@ this property. \p{Script: Tavt} \p{Script=Tai_Viet} (72) \p{Script: Telu} \p{Script=Telugu} (93) \p{Script: Telugu} (Short: \p{Sc=Telu}, \p{Telu}) (93) - \p{Script: Tfng} \p{Script=Tifinagh} (55) + \p{Script: Tfng} \p{Script=Tifinagh} (57) \p{Script: Tglg} \p{Script=Tagalog} (20) \p{Script: Thaa} \p{Script=Thaana} (50) \p{Script: Thaana} (Short: \p{Sc=Thaa}, \p{Thaa}) (50) \p{Script: Thai} (Short: \p{Sc=Thai}, \p{Thai}) (86) - \p{Script: Tibetan} (Short: \p{Sc=Tibt}, \p{Tibt}) (201) - \p{Script: Tibt} \p{Script=Tibetan} (201) - \p{Script: Tifinagh} (Short: \p{Sc=Tfng}, \p{Tfng}) (55) + \p{Script: Tibetan} (Short: \p{Sc=Tibt}, \p{Tibt}) (207) + \p{Script: Tibt} \p{Script=Tibetan} (207) + \p{Script: Tifinagh} (Short: \p{Sc=Tfng}, \p{Tfng}) (57) \p{Script: Ugar} \p{Script=Ugaritic} (31) \p{Script: Ugaritic} (Short: \p{Sc=Ugar}, \p{Ugar}) (31) - \p{Script: Unknown} (Short: \p{Sc=Zzzz}, \p{Zzzz}) (1_006_751) + \p{Script: Unknown} (Short: \p{Sc=Zzzz}, \p{Zzzz}) (1_004_663) \p{Script: Vai} (Short: \p{Sc=Vai}, \p{Vai}) (300) \p{Script: Vaii} \p{Script=Vai} (300) \p{Script: Xpeo} \p{Script=Old_Persian} (50) @@ -2596,8 +2679,8 @@ this property. \p{Script: Yi} (Short: \p{Sc=Yi}, \p{Yi}) (1220) \p{Script: Yiii} \p{Script=Yi} (1220) \p{Script: Zinh} \p{Script=Inherited} (523) - \p{Script: Zyyy} \p{Script=Common} (5395) - \p{Script: Zzzz} \p{Script=Unknown} (1_006_751) + \p{Script: Zyyy} \p{Script=Common} (6379) + \p{Script: Zzzz} \p{Script=Unknown} (1_004_663) \p{SD} \p{Soft_Dotted} (= \p{Soft_Dotted=Y}) (46) \p{SD: *} \p{Soft_Dotted: *} \p{Sentence_Break: AT} \p{Sentence_Break=ATerm} (4) @@ -2605,28 +2688,28 @@ this property. \p{Sentence_Break: CL} \p{Sentence_Break=Close} (177) \p{Sentence_Break: Close} (Short: \p{SB=CL}) (177) \p{Sentence_Break: CR} (Short: \p{SB=CR}) (1) - \p{Sentence_Break: EX} \p{Sentence_Break=Extend} (1455) - \p{Sentence_Break: Extend} (Short: \p{SB=EX}) (1455) + \p{Sentence_Break: EX} \p{Sentence_Break=Extend} (1502) + \p{Sentence_Break: Extend} (Short: \p{SB=EX}) (1502) \p{Sentence_Break: FO} \p{Sentence_Break=Format} (138) \p{Sentence_Break: Format} (Short: \p{SB=FO}) (138) - \p{Sentence_Break: LE} \p{Sentence_Break=OLetter} (96_405) + \p{Sentence_Break: LE} \p{Sentence_Break=OLetter} (97_369) \p{Sentence_Break: LF} (Short: \p{SB=LF}) (1) - \p{Sentence_Break: LO} \p{Sentence_Break=Lower} (1907) - \p{Sentence_Break: Lower} (Short: \p{SB=LO}) (1907) - \p{Sentence_Break: NU} \p{Sentence_Break=Numeric} (403) - \p{Sentence_Break: Numeric} (Short: \p{SB=NU}) (403) - \p{Sentence_Break: OLetter} (Short: \p{SB=LE}) (96_405) - \p{Sentence_Break: Other} (Short: \p{SB=XX}) (1_012_008) + \p{Sentence_Break: LO} \p{Sentence_Break=Lower} (1917) + \p{Sentence_Break: Lower} (Short: \p{SB=LO}) (1917) + \p{Sentence_Break: NU} \p{Sentence_Break=Numeric} (412) + \p{Sentence_Break: Numeric} (Short: \p{SB=NU}) (412) + \p{Sentence_Break: OLetter} (Short: \p{SB=LE}) (97_369) + \p{Sentence_Break: Other} (Short: \p{SB=XX}) (1_010_959) \p{Sentence_Break: SC} \p{Sentence_Break=SContinue} (26) \p{Sentence_Break: SContinue} (Short: \p{SB=SC}) (26) \p{Sentence_Break: SE} \p{Sentence_Break=Sep} (3) \p{Sentence_Break: Sep} (Short: \p{SB=SE}) (3) \p{Sentence_Break: Sp} (Short: \p{SB=Sp}) (21) - \p{Sentence_Break: ST} \p{Sentence_Break=STerm} (63) - \p{Sentence_Break: STerm} (Short: \p{SB=ST}) (63) - \p{Sentence_Break: UP} \p{Sentence_Break=Upper} (1500) - \p{Sentence_Break: Upper} (Short: \p{SB=UP}) (1500) - \p{Sentence_Break: XX} \p{Sentence_Break=Other} (1_012_008) + \p{Sentence_Break: ST} \p{Sentence_Break=STerm} (73) + \p{Sentence_Break: STerm} (Short: \p{SB=ST}) (73) + \p{Sentence_Break: UP} \p{Sentence_Break=Upper} (1509) + \p{Sentence_Break: Upper} (Short: \p{SB=UP}) (1509) + \p{Sentence_Break: XX} \p{Sentence_Break=Other} (1_010_959) \p{Separator} \p{General_Category=Separator} (Short: \p{Z}) (20) \p{Shavian} \p{Script=Shavian} (Short: \p{Shaw}) (48) @@ -2637,12 +2720,12 @@ this property. \p{Block=Sinhala}) (80) \p{Sk} \p{Modifier_Symbol} (= \p{General_Category=Modifier_Symbol}) - (99) + (115) \p{Sm} \p{Math_Symbol} (= \p{General_Category= - Math_Symbol}) (945) + Math_Symbol}) (948) X \p{Small_Form_Variants} \p{Block=Small_Form_Variants} (32) \p{So} \p{Other_Symbol} (= \p{General_Category= - Other_Symbol}) (3409) + Other_Symbol}) (4398) \p{Soft_Dotted} \p{Soft_Dotted=Y} (Short: \p{SD}) (46) \p{Soft_Dotted: N*} (Short: \p{SD=N}, \P{SD}) (1_114_066) \p{Soft_Dotted: Y*} (Short: \p{SD=Y}, \p{SD}) (46) @@ -2651,15 +2734,15 @@ this property. \p{Space: *} \p{White_Space: *} \p{Space_Separator} \p{General_Category=Space_Separator} (Short: \p{Zs}) (18) - \p{SpacePerl} \s, including beyond ASCII (25) + \p{SpacePerl} \p{XPerlSpace} (25) \p{Spacing_Mark} \p{General_Category=Spacing_Mark} (Short: - \p{Mc}) (276) + \p{Mc}) (287) X \p{Spacing_Modifier_Letters} \p{Block=Spacing_Modifier_Letters} (80) X \p{Specials} \p{Block=Specials} (16) - \p{STerm} \p{STerm=Y} (66) - \p{STerm: N*} (Single: \P{STerm}) (1_114_046) - \p{STerm: Y*} (Single: \p{STerm}) (66) + \p{STerm} \p{STerm=Y} (76) + \p{STerm: N*} (Single: \P{STerm}) (1_114_036) + \p{STerm: Y*} (Single: \p{STerm}) (76) \p{Sund} \p{Sundanese} (= \p{Script=Sundanese}) (NOT \p{Block=Sundanese}) (55) \p{Sundanese} \p{Script=Sundanese} (Short: \p{Sund}; NOT @@ -2687,7 +2770,7 @@ this property. \p{Syloti_Nagri} \p{Script=Syloti_Nagri} (Short: \p{Sylo}; NOT \p{Block=Syloti_Nagri}) (44) \p{Symbol} \p{General_Category=Symbol} (Short: \p{S}) - (4499) + (5508) \p{Syrc} \p{Syriac} (= \p{Script=Syriac}) (NOT \p{Block=Syriac}) (77) \p{Syriac} \p{Script=Syriac} (Short: \p{Syrc}; NOT @@ -2721,15 +2804,15 @@ this property. \p{Telugu} \p{Script=Telugu} (Short: \p{Telu}; NOT \p{Block=Telugu}) (93) \p{Term} \p{Terminal_Punctuation} (= - \p{Terminal_Punctuation=Y}) (161) + \p{Terminal_Punctuation=Y}) (169) \p{Term: *} \p{Terminal_Punctuation: *} \p{Terminal_Punctuation} \p{Terminal_Punctuation=Y} (Short: - \p{Term}) (161) + \p{Term}) (169) \p{Terminal_Punctuation: N*} (Short: \p{Term=N}, \P{Term}) - (1_113_951) - \p{Terminal_Punctuation: Y*} (Short: \p{Term=Y}, \p{Term}) (161) + (1_113_943) + \p{Terminal_Punctuation: Y*} (Short: \p{Term=Y}, \p{Term}) (169) \p{Tfng} \p{Tifinagh} (= \p{Script=Tifinagh}) (NOT - \p{Block=Tifinagh}) (55) + \p{Block=Tifinagh}) (57) \p{Tglg} \p{Tagalog} (= \p{Script=Tagalog}) (NOT \p{Block=Tagalog}) (20) \p{Thaa} \p{Thaana} (= \p{Script=Thaana}) (NOT @@ -2738,24 +2821,27 @@ this property. \p{Block=Thaana}) (50) \p{Thai} \p{Script=Thai} (NOT \p{Block=Thai}) (86) \p{Tibetan} \p{Script=Tibetan} (Short: \p{Tibt}; NOT - \p{Block=Tibetan}) (201) + \p{Block=Tibetan}) (207) \p{Tibt} \p{Tibetan} (= \p{Script=Tibetan}) (NOT - \p{Block=Tibetan}) (201) + \p{Block=Tibetan}) (207) \p{Tifinagh} \p{Script=Tifinagh} (Short: \p{Tfng}; NOT - \p{Block=Tifinagh}) (55) - \p{Title} \p{General_Category=Titlecase_Letter} - (Short: \p{Lt}) (31) - \p{Titlecase_Letter} \p{Title} (= \p{General_Category= - Titlecase_Letter}) (31) + \p{Block=Tifinagh}) (57) + \p{Title} (/i= Cased=Yes) (31) + \p{Titlecase} \p{Title} (/i= Cased=Yes) (31) + \p{Titlecase_Letter} \p{General_Category=Titlecase_Letter} + (Short: \p{Lt}; /i= General_Category= + Cased_Letter) (31) + X \p{Transport_And_Map_Symbols} \p{Block=Transport_And_Map_Symbols} + (128) \p{Ugar} \p{Ugaritic} (= \p{Script=Ugaritic}) (NOT \p{Block=Ugaritic}) (31) \p{Ugaritic} \p{Script=Ugaritic} (Short: \p{Ugar}; NOT \p{Block=Ugaritic}) (31) \p{UIdeo} \p{Unified_Ideograph} (= - \p{Unified_Ideograph=Y}) (74_394) + \p{Unified_Ideograph=Y}) (74_616) \p{UIdeo: *} \p{Unified_Ideograph: *} \p{Unassigned} \p{General_Category=Unassigned} (Short: - \p{Cn}) (867_235) + \p{Cn}) (865_147) X \p{Unified_Canadian_Aboriginal_Syllabics} \p{Block= Unified_Canadian_Aboriginal_Syllabics} (Short: \p{InCanadianSyllabics}) (640) @@ -2763,19 +2849,23 @@ this property. Unified_Canadian_Aboriginal_Syllabics_- Extended} (80) \p{Unified_Ideograph} \p{Unified_Ideograph=Y} (Short: \p{UIdeo}) - (74_394) + (74_616) \p{Unified_Ideograph: N*} (Short: \p{UIdeo=N}, \P{UIdeo}) - (1_039_718) - \p{Unified_Ideograph: Y*} (Short: \p{UIdeo=Y}, \p{UIdeo}) (74_394) + (1_039_496) + \p{Unified_Ideograph: Y*} (Short: \p{UIdeo=Y}, \p{UIdeo}) (74_616) \p{Unknown} \p{Script=Unknown} (Short: \p{Zzzz}) - (1_006_751) - \p{Upper} \p{Uppercase=Y} (1469) + (1_004_663) + \p{Upper} \p{Uppercase=Y} (/i= Cased=Yes) (1478) \p{Upper: *} \p{Uppercase: *} - \p{Uppercase} \p{Upper} (= \p{Uppercase=Y}) (1469) - \p{Uppercase: N*} (Short: \p{Upper=N}, \P{Upper}) (1_112_643) - \p{Uppercase: Y*} (Short: \p{Upper=Y}, \p{Upper}) (1469) + \p{Uppercase} \p{Upper} (= \p{Uppercase=Y}) (/i= Cased= + Yes) (1478) + \p{Uppercase: N*} (Short: \p{Upper=N}, \P{Upper}; /i= Cased= + No) (1_112_634) + \p{Uppercase: Y*} (Short: \p{Upper=Y}, \p{Upper}; /i= Cased= + Yes) (1478) \p{Uppercase_Letter} \p{General_Category=Uppercase_Letter} - (Short: \p{Lu}) (1427) + (Short: \p{Lu}; /i= General_Category= + Cased_Letter) (1436) \p{Vai} \p{Script=Vai} (NOT \p{Block=Vai}) (300) \p{Vaii} \p{Vai} (= \p{Script=Vai}) (NOT \p{Block= Vai}) (300) @@ -2797,17 +2887,18 @@ this property. \p{White_Space: N*} (Short: \p{Space=N}, \P{WSpace}) (1_114_086) \p{White_Space: Y*} (Short: \p{Space=Y}, \p{WSpace}) (26) - \p{Word} \w, including beyond ASCII (101_685) - \p{Word_Break: ALetter} (Short: \p{WB=LE}) (23_694) + \p{Word} \w, including beyond ASCII; = \p{Alnum} + + \pM + \p{Pc} (102_724) + \p{Word_Break: ALetter} (Short: \p{WB=LE}) (24_453) \p{Word_Break: CR} (Short: \p{WB=CR}) (1) \p{Word_Break: EX} \p{Word_Break=ExtendNumLet} (10) - \p{Word_Break: Extend} (Short: \p{WB=Extend}) (1455) + \p{Word_Break: Extend} (Short: \p{WB=Extend}) (1502) \p{Word_Break: ExtendNumLet} (Short: \p{WB=EX}) (10) \p{Word_Break: FO} \p{Word_Break=Format} (137) \p{Word_Break: Format} (Short: \p{WB=FO}) (137) - \p{Word_Break: KA} \p{Word_Break=Katakana} (309) - \p{Word_Break: Katakana} (Short: \p{WB=KA}) (309) - \p{Word_Break: LE} \p{Word_Break=ALetter} (23_694) + \p{Word_Break: KA} \p{Word_Break=Katakana} (310) + \p{Word_Break: Katakana} (Short: \p{WB=KA}) (310) + \p{Word_Break: LE} \p{Word_Break=ALetter} (24_453) \p{Word_Break: LF} (Short: \p{WB=LF}) (1) \p{Word_Break: MB} \p{Word_Break=MidNumLet} (8) \p{Word_Break: MidLetter} (Short: \p{WB=ML}) (8) @@ -2817,27 +2908,46 @@ this property. \p{Word_Break: MN} \p{Word_Break=MidNum} (15) \p{Word_Break: Newline} (Short: \p{WB=NL}) (5) \p{Word_Break: NL} \p{Word_Break=Newline} (5) - \p{Word_Break: NU} \p{Word_Break=Numeric} (402) - \p{Word_Break: Numeric} (Short: \p{WB=NU}) (402) - \p{Word_Break: Other} (Short: \p{WB=XX}) (1_088_067) - \p{Word_Break: XX} \p{Word_Break=Other} (1_088_067) + \p{Word_Break: NU} \p{Word_Break=Numeric} (411) + \p{Word_Break: Numeric} (Short: \p{WB=NU}) (411) + \p{Word_Break: Other} (Short: \p{WB=XX}) (1_087_251) + \p{Word_Break: XX} \p{Word_Break=Other} (1_087_251) \p{WSpace} \p{White_Space} (= \p{White_Space=Y}) (26) \p{WSpace: *} \p{White_Space: *} \p{XDigit} \p{Hex_Digit=Y} (Short: \p{Hex}) (44) \p{XID_Continue} \p{XID_Continue=Y} (Short: \p{XIDC}) - (101_615) - \p{XID_Continue: N*} (Short: \p{XIDC=N}, \P{XIDC}) (1_012_497) - \p{XID_Continue: Y*} (Short: \p{XIDC=Y}, \p{XIDC}) (101_615) - \p{XID_Start} \p{XID_Start=Y} (Short: \p{XIDS}) (99_741) - \p{XID_Start: N*} (Short: \p{XIDS=N}, \P{XIDS}) (1_014_371) - \p{XID_Start: Y*} (Short: \p{XIDS=Y}, \p{XIDS}) (99_741) + (102_656) + \p{XID_Continue: N*} (Short: \p{XIDC=N}, \P{XIDC}) (1_011_456) + \p{XID_Continue: Y*} (Short: \p{XIDC=Y}, \p{XIDC}) (102_656) + \p{XID_Start} \p{XID_Start=Y} (Short: \p{XIDS}) (100_724) + \p{XID_Start: N*} (Short: \p{XIDS=N}, \P{XIDS}) (1_013_388) + \p{XID_Start: Y*} (Short: \p{XIDS=Y}, \p{XIDS}) (100_724) \p{XIDC} \p{XID_Continue} (= \p{XID_Continue=Y}) - (101_615) + (102_656) \p{XIDC: *} \p{XID_Continue: *} - \p{XIDS} \p{XID_Start} (= \p{XID_Start=Y}) (99_741) + \p{XIDS} \p{XID_Start} (= \p{XID_Start=Y}) (100_724) \p{XIDS: *} \p{XID_Start: *} \p{Xpeo} \p{Old_Persian} (= \p{Script=Old_Persian}) (NOT \p{Block=Old_Persian}) (50) + \p{XPerlSpace} \s, including beyond ASCII (Short: + \p{SpacePerl}) (25) + \p{XPosixAlnum} \p{Alnum} (101_959) + \p{XPosixAlpha} \p{Alpha} (= \p{Alphabetic=Y}) (101_539) + \p{XPosixBlank} \p{Blank} (19) + \p{XPosixCntrl} \p{Cntrl} (= \p{General_Category=Control}) + (65) + \p{XPosixDigit} \p{Digit} (= \p{General_Category= + Decimal_Number}) (420) + \p{XPosixGraph} \p{Graph} (246_832) + \p{XPosixLower} \p{Lower} (= \p{Lowercase=Y}) (/i= Cased= + Yes) (1918) + \p{XPosixPrint} \p{Print} (246_850) + \p{XPosixPunct} \p{Punct} + ASCII-range \p{Symbol} (607) + \p{XPosixSpace} \p{Space} (= \p{White_Space=Y}) (26) + \p{XPosixUpper} \p{Upper} (= \p{Uppercase=Y}) (/i= Cased= + Yes) (1478) + \p{XPosixWord} \p{Word} (102_724) + \p{XPosixXDigit} \p{XDigit} (= \p{Hex_Digit=Y}) (44) \p{Xsux} \p{Cuneiform} (= \p{Script=Cuneiform}) (NOT \p{Block=Cuneiform}) (982) \p{Yi} \p{Script=Yi} (1220) @@ -2857,20 +2967,20 @@ this property. \p{Zs} \p{Space_Separator} (= \p{General_Category=Space_Separator}) (18) - \p{Zyyy} \p{Common} (= \p{Script=Common}) (5395) + \p{Zyyy} \p{Common} (= \p{Script=Common}) (6379) \p{Zzzz} \p{Unknown} (= \p{Script=Unknown}) - (1_006_751) + (1_004_663) T \p{_CanonDCIJ} (For internal use by Perl, not necessarily stable) (= \p{Soft_Dotted=Y}) (46) T \p{_Case_Ignorable} (For internal use by Perl, not necessarily - stable) (= \p{Case_Ignorable=Y}) (1632) + stable) (= \p{Case_Ignorable=Y}) (1692) T \p{_CombAbove} (For internal use by Perl, not necessarily stable) (= \p{Canonical_Combining_Class= - Above}) (318) + Above}) (320) T \p{_X_Begin} (For internal use by Perl, not necessarily stable) (1_113_907) T \p{_X_Extend} (For internal use by Perl, not necessarily - stable) (1462) + stable) (1509) T \p{_X_LV_LVT_V} (For internal use by Perl, not necessarily stable) (11_267) @@ -2897,6 +3007,7 @@ version of Unicode, the following match zero code points: A few properties are accessible in Perl via various function calls only. These are: + Lowercase_Mapping lc() and lcfirst() Titlecase_Mapping ucfirst() Uppercase_Mapping uc() @@ -2905,8 +3016,8 @@ Case_Folding is accessible through the /i modifier in regular expressions. The Name property is accessible through the \N{} interpolation in double-quoted strings and regular expressions, but both usages require a C<use -charnames;> to be specified, which also contains related functions viacode() -and vianame(). +charnames;> to be specified, which also contains related functions viacode(), +vianame(), and string_vianame(). =head1 Unicode regular expression properties that are NOT accepted by Perl @@ -2919,79 +3030,70 @@ the properties are listed enclosed in (parentheses). - - + + =item I<Expands_On_NFC> (XO_NFC) - + =item I<Expands_On_NFD> (XO_NFD) - + =item I<Expands_On_NFKC> (XO_NFKC) - + =item I<Expands_On_NFKD> (XO_NFKD) - -Easily computed, and yet doesn't cover the common encoding forms (UTF-16/8) - - +Deprecated by Unicode. These are characters that expand to more than one character in the specified normalization form, but whether they actually take up more bytes or not depends on the encoding being used. For example, a UTF-8 encoded character may expand to a different number of bytes than a UTF-32 encoded character. + + + + - =item I<Grapheme_Link> (Gr_Link) - -Deprecated by Unicode. Use ccc=vr (Canonical_Combining_Class=Virama) instead - - +Deprecated by Unicode: Duplicates ccc=vr (Canonical_Combining_Class=Virama) + + + + - =item I<Jamo_Short_Name> (JSN) - + Used by Unicode internally for generating other properties and not intended to be used stand-alone - - - + + + =item I<Script=Katakana_Or_Hiragana> (sc=Hrkt) - + Obsolete. All code points previously matched by this have been moved to "Script=Common" - - - + =back -An installation can choose to allow any of these to be matched by changing the -controlling lists contained in the program C<$Config{privlib}>/F<unicore/mktables> -and then re-running F<mktables>. (C<%Config> is available from the Config module). +An installation can choose to allow any of these to be matched by downloading +the Unicode database from L<http://www.unicode.org/Public/> to +C<$Config{privlib}>/F<unicore/> in the Perl source tree, changing the +controlling lists contained in the program +C<$Config{privlib}>/F<unicore/mktables> and then re-compiling and installing. +(C<%Config> is available from the Config module). =head1 Files in the I<To> directory (for serious hackers only) All Unicode properties are really mappings (in the mathematical sense) from code points to their respective values. As part of its build process, Perl constructs tables containing these mappings for all properties that it -deals with. But only a few of these are written out into files. +deals with. Some, but not all, of these are written out into files. Those written out are in the directory C<$Config{privlib}>/F<unicore/To/> (%Config is available from the Config module). -Those ones written are ones needed by Perl internally during execution, or for -which there is some demand, and those for which there is no access through the -Perl core. Generally, properties that can be used in regular expression -matching do not have their map tables written, like Script. Nor are the -simplistic properties that have a better, more complete version, such as -Simple_Uppercase_Mapping (Uppercase_Mapping is written instead). - -None of the properties in the I<To> directory are currently directly -accessible through the Perl core, although some may be accessed indirectly. -For example, the uc() function implements the Uppercase_Mapping property and -uses the F<Upper.pl> file found in this directory. - -The available files with their properties (short names in parentheses), -and any flags or comments about them, are: +Perl reserves the right to change the format and even the existence of any of +those files without notice, except the ones that were in existence prior to +release 5.13. If those change, a deprecation cycle will be done first. These +are: Bmg.pl Bidi_Mirroring_Glyph (bmg) Digit.pl Perl_Decimal_Digit @@ -3002,12 +3104,8 @@ and any flags or comments about them, are: Upper.pl Uppercase_Mapping (uc) -An installation can choose to change which files are generated by changing the -controlling lists contained in the program C<$Config{privlib}>/F<unicore/mktables> -and then re-running F<mktables>. - -Each of these files defines two hash entries to help reading programs decipher -it. One of them looks like this: +Each of the files in this directory defines two hash entries to help reading +programs decipher it. One of them looks like this: $utf8::SwashInfo{'ToNAME'}{'format'} = 's'; @@ -3017,11 +3115,12 @@ also for backwards compatibility.) The hash entry gives the format of the mapping fields of the table, currently one of the following: b binary + c Perl's internal (Normalize.pm) decomposition mapping d single decimal digit f floating point number i integer r rational: an integer or a fraction - s arbitrary string + s string x positive hex whole number; a code point diff --git a/Master/tlpkg/tlperl/lib/pods/perlunitut.pod b/Master/tlpkg/tlperl/lib/pods/perlunitut.pod index fc352d5aad1..9e5af04ec79 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlunitut.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlunitut.pod @@ -42,8 +42,8 @@ distinction between code point and character is blurred, so the terms often are used interchangeably.) There are many, many code points, but computers work with bytes, and a byte has -room for only 256 values. Unicode has many more characters, so you need a -method to make these accessible. +room for only 256 values. Unicode has many more characters than that, +so you need a method to make these accessible. Unicode is encoded using several competing encodings, of which UTF-8 is the most used. In a Unicode encoding, multiple subsequent bytes can be used to diff --git a/Master/tlpkg/tlperl/lib/pods/perlutil.pod b/Master/tlpkg/tlperl/lib/pods/perlutil.pod index 453248d2497..53ecb5986d3 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlutil.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlutil.pod @@ -75,7 +75,7 @@ typeset PostScript or text file of the whole lot. =back -=head2 Convertors +=head2 Converters To help you convert legacy programs to Perl, we've included three conversion filters: @@ -253,6 +253,11 @@ archive and an unextracted one. (Note that this utility requires the C<Text::Diff> module to function properly; this module isn't distributed with perl, but is available from the CPAN.) +=item L<ptargrep> + +F<ptargrep> is a utility to apply pattern matching to the contents of files +in a tar archive. + =item L<shasum> This utility, that comes with the C<Digest::SHA> module, is used to print diff --git a/Master/tlpkg/tlperl/lib/pods/perlvar.pod b/Master/tlpkg/tlperl/lib/pods/perlvar.pod index bc04dcb9c55..39bab245bb3 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlvar.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlvar.pod @@ -4,120 +4,77 @@ perlvar - Perl predefined variables =head1 DESCRIPTION -=head2 Predefined Names +=head2 The Syntax of Variable Names -The following names have special meaning to Perl. Most -punctuation names have reasonable mnemonics, or analogs in the -shells. Nevertheless, if you wish to use long variable names, -you need only say - - use English; - -at the top of your program. This aliases all the short names to the long -names in the current package. Some even have medium names, generally -borrowed from B<awk>. In general, it's best to use the - - use English '-no_match_vars'; - -invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it avoids -a certain performance hit with the use of regular expressions. See -L<English>. - -Variables that depend on the currently selected filehandle may be set by -calling an appropriate object method on the IO::Handle object, although -this is less efficient than using the regular built-in variables. (Summary -lines below for this contain the word HANDLE.) First you must say - - use IO::Handle; - -after which you may use either - - method HANDLE EXPR - -or more safely, - - HANDLE->method(EXPR) - -Each method returns the old value of the IO::Handle attribute. -The methods each take an optional EXPR, which, if supplied, specifies the -new value for the IO::Handle attribute in question. If not supplied, -most methods do nothing to the current value--except for -autoflush(), which will assume a 1 for you, just to be different. - -Because loading in the IO::Handle class is an expensive operation, you should -learn how to use the regular built-in variables. - -A few of these variables are considered "read-only". This means that if -you try to assign to this variable, either directly or indirectly through -a reference, you'll raise a run-time exception. - -You should be very careful when modifying the default values of most -special variables described in this document. In most cases you want -to localize these variables before changing them, since if you don't, -the change may affect other modules which rely on the default values -of the special variables that you have changed. This is one of the -correct ways to read the whole file at once: - - open my $fh, "<", "foo" or die $!; - local $/; # enable localized slurp mode - my $content = <$fh>; - close $fh; - -But the following code is quite bad: - - open my $fh, "<", "foo" or die $!; - undef $/; # enable slurp mode - my $content = <$fh>; - close $fh; - -since some other module, may want to read data from some file in the -default "line mode", so if the code we have just presented has been -executed, the global value of C<$/> is now changed for any other code -running inside the same Perl interpreter. +Variable names in Perl can have several formats. Usually, they +must begin with a letter or underscore, in which case they can be +arbitrarily long (up to an internal limit of 251 characters) and +may contain letters, digits, underscores, or the special sequence +C<::> or C<'>. In this case, the part before the last C<::> or +C<'> is taken to be a I<package qualifier>; see L<perlmod>. -Usually when a variable is localized you want to make sure that this -change affects the shortest scope possible. So unless you are already -inside some short C<{}> block, you should create one yourself. For -example: +Perl variable names may also be a sequence of digits or a single +punctuation or control character. These names are all reserved for +special uses by Perl; for example, the all-digits names are used +to hold data captured by backreferences after a regular expression +match. Perl has a special syntax for the single-control-character +names: It understands C<^X> (caret C<X>) to mean the control-C<X> +character. For example, the notation C<$^W> (dollar-sign caret +C<W>) is the scalar variable whose name is the single character +control-C<W>. This is better than typing a literal control-C<W> +into your program. - my $content = ''; - open my $fh, "<", "foo" or die $!; - { - local $/; - $content = <$fh>; - } - close $fh; +Since Perl 5.6, Perl variable names may be alphanumeric +strings that begin with control characters (or better yet, a caret). +These variables must be written in the form C<${^Foo}>; the braces +are not optional. C<${^Foo}> denotes the scalar variable whose +name is a control-C<F> followed by two C<o>'s. These variables are +reserved for future special uses by Perl, except for the ones that +begin with C<^_> (control-underscore or caret-underscore). No +control-character name that begins with C<^_> will acquire a special +meaning in any future version of Perl; such names may therefore be +used safely in programs. C<$^_> itself, however, I<is> reserved. -Here is an example of how your own code can go broken: +Perl identifiers that begin with digits, control characters, or +punctuation characters are exempt from the effects of the C<package> +declaration and are always forced to be in package C<main>; they are +also exempt from C<strict 'vars'> errors. A few other names are also +exempt in these ways: - for (1..5){ - nasty_break(); - print "$_ "; - } - sub nasty_break { - $_ = 5; - # do something with $_ - } + ENV STDIN + INC STDOUT + ARGV STDERR + ARGVOUT + SIG -You probably expect this code to print: +In particular, the special C<${^_XYZ}> variables are always taken +to be in package C<main>, regardless of any C<package> declarations +presently in scope. - 1 2 3 4 5 +=head1 SPECIAL VARIABLES -but instead you get: +The following names have special meaning to Perl. Most punctuation +names have reasonable mnemonics, or analogs in the shells. +Nevertheless, if you wish to use long variable names, you need only say: - 5 5 5 5 5 + use English; -Why? Because nasty_break() modifies C<$_> without localizing it -first. The fix is to add local(): +at the top of your program. This aliases all the short names to the long +names in the current package. Some even have medium names, generally +borrowed from B<awk>. To avoid a performance hit, if you don't need the +C<$PREMATCH>, C<$MATCH>, or C<$POSTMATCH> it's best to use the C<English> +module without them: - local $_ = 5; + use English '-no_match_vars'; -It's easy to notice the problem in such a short example, but in more -complicated code you are looking for trouble if you don't localize -changes to the special variables. +Before you continue, note the sort order for variables. In general, we +first list the variables in case-insensitive, almost-lexigraphical +order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}> +or C<$^T>), although C<$_> and C<@_> move up to the top of the pile. +For variables with the same identifier, we list it in order of scalar, +array, hash, and bareword. -The following list is ordered by scalar variables first, then the -arrays, then the hashes. +=head2 General Variables =over 8 @@ -126,29 +83,28 @@ arrays, then the hashes. =item $_ X<$_> X<$ARG> -The default input and pattern-searching space. The following pairs are +The default input and pattern-searching space. The following pairs are equivalent: - while (<>) {...} # equivalent only in while! - while (defined($_ = <>)) {...} + while (<>) {...} # equivalent only in while! + while (defined($_ = <>)) {...} - /^Subject:/ - $_ =~ /^Subject:/ + /^Subject:/ + $_ =~ /^Subject:/ - tr/a-z/A-Z/ - $_ =~ tr/a-z/A-Z/ + tr/a-z/A-Z/ + $_ =~ tr/a-z/A-Z/ - chomp - chomp($_) + chomp + chomp($_) -Here are the places where Perl will assume $_ even if you -don't use it: +Here are the places where Perl will assume C<$_> even if you don't use it: =over 3 =item * -The following functions: +The following functions use C<$_> as a default argument: abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob, hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, @@ -161,7 +117,6 @@ unlink, unpack. All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN. See L<perlfunc/-X> - =item * The pattern matching operations C<m//>, C<s///> and C<tr///> (aka C<y///>) @@ -174,1267 +129,1387 @@ variable is supplied. =item * -The implicit iterator variable in the grep() and map() functions. +The implicit iterator variable in the C<grep()> and C<map()> functions. =item * -The implicit variable of given(). +The implicit variable of C<given()>. =item * The default place to put an input record when a C<< <FH> >> operation's result is tested by itself as the sole criterion of a C<while> -test. Outside a C<while> test, this will not happen. +test. Outside a C<while> test, this will not happen. =back As C<$_> is a global variable, this may lead in some cases to unwanted -side-effects. As of perl 5.9.1, you can now use a lexical version of -C<$_> by declaring it in a file or in a block with C<my>. Moreover, +side-effects. As of perl 5.9.1, you can now use a lexical version of +C<$_> by declaring it in a file or in a block with C<my>. Moreover, declaring C<our $_> restores the global C<$_> in the current scope. -(Mnemonic: underline is understood in certain operations.) +Mnemonic: underline is understood in certain operations. -=back +=item @ARG -=over 8 +=item @_ +X<@_> X<@ARG> -=item $a +Within a subroutine the array C<@_> contains the parameters passed to +that subroutine. Inside a subroutine, C<@_> is the default array for +the array operators C<push>, C<pop>, C<shift>, and C<unshift>. -=item $b -X<$a> X<$b> +See L<perlsub>. -Special package variables when using sort(), see L<perlfunc/sort>. -Because of this specialness $a and $b don't need to be declared -(using use vars, or our()) even when using the C<strict 'vars'> pragma. -Don't lexicalize them with C<my $a> or C<my $b> if you want to be -able to use them in the sort() comparison block or function. +=item $LIST_SEPARATOR -=back +=item $" +X<$"> X<$LIST_SEPARATOR> -=over 8 +When an array or an array slice is interpolated into a double-quoted +string or a similar context such as C</.../>, its elements are +separated by this value. Default is a space. For example, this: -=item $<I<digits>> ($1, $2, ...) -X<$1> X<$2> X<$3> + print "The array is: @array\n"; -Contains the subpattern from the corresponding set of capturing -parentheses from the last successful pattern match, not counting patterns -matched in nested blocks that have been exited already. (Mnemonic: -like \digits.) These variables are all read-only and dynamically -scoped to the current BLOCK. +is equivalent to this: -=item $MATCH + print "The array is: " . join($", @array) . "\n"; -=item $& -X<$&> X<$MATCH> +Mnemonic: works in double-quoted context. -The string matched by the last successful pattern match (not counting -any matches hidden within a BLOCK or eval() enclosed by the current -BLOCK). (Mnemonic: like & in some editors.) This variable is read-only -and dynamically scoped to the current BLOCK. +=item $PROCESS_ID -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L</BUGS>. +=item $PID -See L</@-> for a replacement. +=item $$ +X<$$> X<$PID> X<$PROCESS_ID> -=item ${^MATCH} -X<${^MATCH}> +The process number of the Perl running this script. You should +consider this variable read-only, although it will be altered +across C<fork()> calls. -This is similar to C<$&> (C<$MATCH>) except that it does not incur the -performance penalty associated with that variable, and is only guaranteed -to return a defined value when the pattern was compiled or executed with -the C</p> modifier. +Note for Linux users: on Linux, the C functions C<getpid()> and +C<getppid()> return different values from different threads. In order to +be portable, this behavior is not reflected by C<$$>, whose value remains +consistent across threads. If you want to call the underlying C<getpid()>, +you may use the CPAN module C<Linux::Pid>. -=item $PREMATCH +Mnemonic: same as shells. -=item $` -X<$`> X<$PREMATCH> +=item $REAL_GROUP_ID -The string preceding whatever was matched by the last successful -pattern match (not counting any matches hidden within a BLOCK or eval -enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted -string.) This variable is read-only. +=item $GID -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L</BUGS>. +=item $( +X<$(> X<$GID> X<$REAL_GROUP_ID> -See L</@-> for a replacement. +The real gid of this process. If you are on a machine that supports +membership in multiple groups simultaneously, gives a space separated +list of groups you are in. The first number is the one returned by +C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be +the same as the first number. -=item ${^PREMATCH} -X<${^PREMATCH}> +However, a value assigned to C<$(> must be a single number used to +set the real gid. So the value given by C<$(> should I<not> be assigned +back to C<$(> without being forced numeric, such as by adding zero. Note +that this is different to the effective gid (C<$)>) which does take a +list. -This is similar to C<$`> ($PREMATCH) except that it does not incur the -performance penalty associated with that variable, and is only guaranteed -to return a defined value when the pattern was compiled or executed with -the C</p> modifier. +You can change both the real gid and the effective gid at the same +time by using C<POSIX::setgid()>. Changes to C<$(> require a check to C<$!> +to detect any possible errors after an attempted change. -=item $POSTMATCH +Mnemonic: parentheses are used to I<group> things. The real gid is the +group you I<left>, if you're running setgid. -=item $' -X<$'> X<$POSTMATCH> +=item $EFFECTIVE_GROUP_ID -The string following whatever was matched by the last successful -pattern match (not counting any matches hidden within a BLOCK or eval() -enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted -string.) Example: +=item $EGID - local $_ = 'abcdefghi'; - /def/; - print "$`:$&:$'\n"; # prints abc:def:ghi +=item $) +X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID> -This variable is read-only and dynamically scoped to the current BLOCK. +The effective gid of this process. If you are on a machine that +supports membership in multiple groups simultaneously, gives a space +separated list of groups you are in. The first number is the one +returned by C<getegid()>, and the subsequent ones by C<getgroups()>, +one of which may be the same as the first number. -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L</BUGS>. +Similarly, a value assigned to C<$)> must also be a space-separated +list of numbers. The first number sets the effective gid, and +the rest (if any) are passed to C<setgroups()>. To get the effect of an +empty list for C<setgroups()>, just repeat the new effective gid; that is, +to force an effective gid of 5 and an effectively empty C<setgroups()> +list, say C< $) = "5 5" >. -See L</@-> for a replacement. +You can change both the effective gid and the real gid at the same +time by using C<POSIX::setgid()> (use only a single numeric argument). +Changes to C<$)> require a check to C<$!> to detect any possible errors +after an attempted change. -=item ${^POSTMATCH} -X<${^POSTMATCH}> +C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on +machines that support the corresponding I<set[re][ug]id()> routine. C<$(> +and C<$)> can be swapped only on machines supporting C<setregid()>. -This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the -performance penalty associated with that variable, and is only guaranteed -to return a defined value when the pattern was compiled or executed with -the C</p> modifier. +Mnemonic: parentheses are used to I<group> things. The effective gid +is the group that's I<right> for you, if you're running setgid. -=item $LAST_PAREN_MATCH +=item $PROGRAM_NAME -=item $+ -X<$+> X<$LAST_PAREN_MATCH> +=item $0 +X<$0> X<$PROGRAM_NAME> -The text matched by the last bracket of the last successful search pattern. -This is useful if you don't know which one of a set of alternative patterns -matched. For example: +Contains the name of the program being executed. - /Version: (.*)|Revision: (.*)/ && ($rev = $+); +On some (but not all) operating systems assigning to C<$0> modifies +the argument area that the C<ps> program sees. On some platforms you +may have to use special C<ps> options or a different C<ps> to see the +changes. Modifying the C<$0> is more useful as a way of indicating the +current program state than it is for hiding the program you're +running. -(Mnemonic: be positive and forward looking.) -This variable is read-only and dynamically scoped to the current BLOCK. +Note that there are platform-specific limitations on the maximum +length of C<$0>. In the most extreme case it may be limited to the +space occupied by the original C<$0>. -=item $LAST_SUBMATCH_RESULT +In some platforms there may be arbitrary amount of padding, for +example space characters, after the modified name as shown by C<ps>. +In some platforms this padding may extend all the way to the original +length of the argument area, no matter what you do (this is the case +for example with Linux 2.2). -=item $^N -X<$^N> +Note for BSD users: setting C<$0> does not completely remove "perl" +from the ps(1) output. For example, setting C<$0> to C<"foobar"> may +result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix +and the " (perl)" suffix are shown depends on your exact BSD variant +and version). This is an operating system feature, Perl cannot help it. -The text matched by the used group most-recently closed (i.e. the group -with the rightmost closing parenthesis) of the last successful search -pattern. (Mnemonic: the (possibly) Nested parenthesis that most -recently closed.) +In multithreaded scripts Perl coordinates the threads so that any +thread may modify its copy of the C<$0> and the change becomes visible +to ps(1) (assuming the operating system plays along). Note that +the view of C<$0> the other threads have will not change since they +have their own copies of it. -This is primarily used inside C<(?{...})> blocks for examining text -recently matched. For example, to effectively capture text to a variable -(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with +If the program has been given to perl via the switches C<-e> or C<-E>, +C<$0> will contain the string C<"-e">. - (?:(...)(?{ $var = $^N })) +On Linux as of perl 5.14 the legacy process name will be set with +C<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> as +perl has done since version 4.000. Now system utilities that read the +legacy process name such as ps, top and killall will recognize the +name you set when assigning to C<$0>. The string you supply will be +cut off at 16 bytes, this is a limitation imposed by Linux. -By setting and then using C<$var> in this way relieves you from having to -worry about exactly which numbered set of parentheses they are. +Mnemonic: same as B<sh> and B<ksh>. -This variable is dynamically scoped to the current BLOCK. +=item $SUBSCRIPT_SEPARATOR -=item @LAST_MATCH_END +=item $SUBSEP -=item @+ -X<@+> X<@LAST_MATCH_END> +=item $; +X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR> -This array holds the offsets of the ends of the last successful -submatches in the currently active dynamic scope. C<$+[0]> is -the offset into the string of the end of the entire match. This -is the same value as what the C<pos> function returns when called -on the variable that was matched against. The I<n>th element -of this array holds the offset of the I<n>th submatch, so -C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset -past where $2 ends, and so on. You can use C<$#+> to determine -how many subgroups were in the last successful match. See the -examples given for the C<@-> variable. +The subscript separator for multidimensional array emulation. If you +refer to a hash element as -=item %LAST_PAREN_MATCH + $foo{$a,$b,$c} -=item %+ -X<%+> +it really means -Similar to C<@+>, the C<%+> hash allows access to the named capture -buffers, should they exist, in the last successful match in the -currently active dynamic scope. + $foo{join($;, $a, $b, $c)} -For example, C<$+{foo}> is equivalent to C<$1> after the following match: +But don't put - 'foo' =~ /(?<foo>foo)/; + @foo{$a,$b,$c} # a slice--note the @ -The keys of the C<%+> hash list only the names of buffers that have -captured (and that are thus associated to defined values). +which means -The underlying behaviour of C<%+> is provided by the -L<Tie::Hash::NamedCapture> module. + ($foo{$a},$foo{$b},$foo{$c}) -B<Note:> C<%-> and C<%+> are tied views into a common internal hash -associated with the last successful regular expression. Therefore mixing -iterative access to them via C<each> may have unpredictable results. -Likewise, if the last successful match changes, then the results may be -surprising. +Default is "\034", the same as SUBSEP in B<awk>. If your keys contain +binary data there might not be any safe value for C<$;>. -=item HANDLE->input_line_number(EXPR) +Consider using "real" multidimensional arrays as described +in L<perllol>. -=item $INPUT_LINE_NUMBER +Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. -=item $NR +=item $REAL_USER_ID -=item $. -X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number> +=item $UID -Current line number for the last filehandle accessed. +=item $< +X<< $< >> X<$UID> X<$REAL_USER_ID> -Each filehandle in Perl counts the number of lines that have been read -from it. (Depending on the value of C<$/>, Perl's idea of what -constitutes a line may not match yours.) When a line is read from a -filehandle (via readline() or C<< <> >>), or when tell() or seek() is -called on it, C<$.> becomes an alias to the line counter for that -filehandle. +The real uid of this process. You can change both the real uid and the +effective uid at the same time by using C<POSIX::setuid()>. Since +changes to C<< $< >> require a system call, check C<$!> after a change +attempt to detect any possible errors. -You can adjust the counter by assigning to C<$.>, but this will not -actually move the seek pointer. I<Localizing C<$.> will not localize -the filehandle's line count>. Instead, it will localize perl's notion -of which filehandle C<$.> is currently aliased to. +Mnemonic: it's the uid you came I<from>, if you're running setuid. -C<$.> is reset when the filehandle is closed, but B<not> when an open -filehandle is reopened without an intervening close(). For more -details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does -an explicit close, line numbers increase across ARGV files (but see -examples in L<perlfunc/eof>). +=item $EFFECTIVE_USER_ID -You can also use C<< HANDLE->input_line_number(EXPR) >> to access the -line counter for a given filehandle without having to worry about -which handle you last accessed. +=item $EUID -(Mnemonic: many programs use "." to mean the current line number.) +=item $> +X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID> -=item IO::Handle->input_record_separator(EXPR) +The effective uid of this process. For example: -=item $INPUT_RECORD_SEPARATOR + $< = $>; # set real to effective uid + ($<,$>) = ($>,$<); # swap real and effective uids -=item $RS +You can change both the effective uid and the real uid at the same +time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check +to C<$!> to detect any possible errors after an attempted change. -=item $/ -X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR> +C<< $< >> and C<< $> >> can be swapped only on machines +supporting C<setreuid()>. -The input record separator, newline by default. This -influences Perl's idea of what a "line" is. Works like B<awk>'s RS -variable, including treating empty lines as a terminator if set to -the null string. (An empty line cannot contain any spaces -or tabs.) You may set it to a multi-character string to match a -multi-character terminator, or to C<undef> to read through the end -of file. Setting it to C<"\n\n"> means something slightly -different than setting to C<"">, if the file contains consecutive -empty lines. Setting to C<""> will treat two or more consecutive -empty lines as a single empty line. Setting to C<"\n\n"> will -blindly assume that the next input character belongs to the next -paragraph, even if it's a newline. (Mnemonic: / delimits -line boundaries when quoting poetry.) +Mnemonic: it's the uid you went I<to>, if you're running setuid. - local $/; # enable "slurp" mode - local $_ = <FH>; # whole file now here - s/\n[ \t]+/ /g; +=item $a -Remember: the value of C<$/> is a string, not a regex. B<awk> has to be -better for something. :-) +=item $b +X<$a> X<$b> -Setting C<$/> to a reference to an integer, scalar containing an integer, or -scalar that's convertible to an integer will attempt to read records -instead of lines, with the maximum record size being the referenced -integer. So this: +Special package variables when using C<sort()>, see L<perlfunc/sort>. +Because of this specialness C<$a> and C<$b> don't need to be declared +(using C<use vars>, or C<our()>) even when using the C<strict 'vars'> +pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to +be able to use them in the C<sort()> comparison block or function. - local $/ = \32768; # or \"32768", or \$var_containing_32768 - open my $fh, "<", $myfile or die $!; - local $_ = <$fh>; +=item $COMPILING -will read a record of no more than 32768 bytes from FILE. If you're -not reading from a record-oriented file (or your OS doesn't have -record-oriented files), then you'll likely get a full chunk of data -with every read. If a record is larger than the record size you've -set, you'll get the record back in pieces. Trying to set the record -size to zero or less will cause reading in the (rest of the) whole file. +=item $^C +X<$^C> X<$COMPILING> -On VMS, record reads are done with the equivalent of C<sysread>, -so it's best not to mix record and non-record reads on the same -file. (This is unlikely to be a problem, because any file you'd -want to read in record mode is probably unusable in line mode.) -Non-VMS systems do normal I/O, so it's safe to mix record and -non-record reads of a file. +The current value of the flag associated with the B<-c> switch. +Mainly of use with B<-MO=...> to allow code to alter its behavior +when being compiled, such as for example to C<AUTOLOAD> at compile +time rather than normal, deferred loading. Setting +C<$^C = 1> is similar to calling C<B::minus_c>. -See also L<perlport/"Newlines">. Also see C<$.>. +This variable was added in Perl 5.6. -=item HANDLE->autoflush(EXPR) +=item $DEBUGGING -=item $OUTPUT_AUTOFLUSH +=item $^D +X<$^D> X<$DEBUGGING> -=item $| -X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH> +The current value of the debugging flags. May be read or set. Like its +command-line equivalent, you can use numeric or symbolic values, eg +C<$^D = 10> or C<$^D = "st">. -If set to nonzero, forces a flush right away and after every write -or print on the currently selected output channel. Default is 0 -(regardless of whether the channel is really buffered by the -system or not; C<$|> tells you only whether you've asked Perl -explicitly to flush after each write). STDOUT will -typically be line buffered if output is to the terminal and block -buffered otherwise. Setting this variable is useful primarily when -you are outputting to a pipe or socket, such as when you are running -a Perl program under B<rsh> and want to see the output as it's -happening. This has no effect on input buffering. See L<perlfunc/getc> -for that. See L<perldoc/select> on how to select the output channel. -See also L<IO::Handle>. (Mnemonic: when you want your pipes to be piping hot.) - -=item IO::Handle->output_field_separator EXPR +Mnemonic: value of B<-D> switch. -=item $OUTPUT_FIELD_SEPARATOR +=item ${^ENCODING} +X<${^ENCODING}> -=item $OFS +The I<object reference> to the C<Encode> object that is used to convert +the source code to Unicode. Thanks to this variable your Perl script +does not have to be written in UTF-8. Default is I<undef>. The direct +manipulation of this variable is highly discouraged. -=item $, -X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR> +This variable was added in Perl 5.8.2. -The output field separator for the print operator. If defined, this -value is printed between each of print's arguments. Default is C<undef>. -(Mnemonic: what is printed when there is a "," in your print statement.) +=item %ENV +X<%ENV> -=item IO::Handle->output_record_separator EXPR +The hash C<%ENV> contains your current environment. Setting a +value in C<ENV> changes the environment for any child processes +you subsequently C<fork()> off. -=item $OUTPUT_RECORD_SEPARATOR +=item $SYSTEM_FD_MAX -=item $ORS +=item $^F +X<$^F> X<$SYSTEM_FD_MAX> -=item $\ -X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR> +The maximum system file descriptor, ordinarily 2. System file +descriptors are passed to C<exec()>ed processes, while higher file +descriptors are not. Also, during an C<open()>, system file descriptors are +preserved even if the C<open()> fails (ordinary file descriptors are +closed before the C<open()> is attempted). The close-on-exec +status of a file descriptor will be decided according to the value of +C<$^F> when the corresponding file, pipe, or socket was opened, not the +time of the C<exec()>. -The output record separator for the print operator. If defined, this -value is printed after the last of print's arguments. Default is C<undef>. -(Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. -Also, it's just like C<$/>, but it's what you get "back" from Perl.) +=item @F +X<@F> -=item $LIST_SEPARATOR +The array C<@F> contains the fields of each line read in when autosplit +mode is turned on. See L<perlrun> for the B<-a> switch. This array +is package-specific, and must be declared or given a full package name +if not in package main when running under C<strict 'vars'>. -=item $" -X<$"> X<$LIST_SEPARATOR> +=item ${^GLOBAL_PHASE} +X<${^GLOBAL_PHASE}> -This is like C<$,> except that it applies to array and slice values -interpolated into a double-quoted string (or similar interpreted -string). Default is a space. (Mnemonic: obvious, I think.) +The current phase of the perl interpreter. -=item $SUBSCRIPT_SEPARATOR +Possible values are: -=item $SUBSEP +=over 8 -=item $; -X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR> +=item CONSTRUCT -The subscript separator for multidimensional array emulation. If you -refer to a hash element as +The C<PerlInterpreter*> is being constructed via C<perl_construct>. This +value is mostly there for completeness and for use via the +underlying C variable C<PL_phase>. It's not really possible for Perl +code to be executed unless construction of the interpreter is +finished. - $foo{$a,$b,$c} +=item START -it really means +This is the global compile-time. That includes, basically, every +C<BEGIN> block executed directly or indirectly from during the +compile-time of the top-level program. - $foo{join($;, $a, $b, $c)} +This phase is not called "BEGIN" to avoid confusion with +C<BEGIN>-blocks, as those are executed during compile-time of any +compilation unit, not just the top-level program. A new, localised +compile-time entered at run-time, for example by constructs as +C<eval "use SomeModule"> are not global interpreter phases, and +therefore aren't reflected by C<${^GLOBAL_PHASE}>. -But don't put +=item CHECK - @foo{$a,$b,$c} # a slice--note the @ +Execution of any C<CHECK> blocks. -which means +=item INIT - ($foo{$a},$foo{$b},$foo{$c}) +Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks. -Default is "\034", the same as SUBSEP in B<awk>. If your -keys contain binary data there might not be any safe value for C<$;>. -(Mnemonic: comma (the syntactic subscript separator) is a -semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already -taken for something more important.) +=item RUN -Consider using "real" multidimensional arrays as described -in L<perllol>. +The main run-time, i.e. the execution of C<PL_main_root>. -=item HANDLE->format_page_number(EXPR) +=item END -=item $FORMAT_PAGE_NUMBER +Execution of any C<END> blocks. -=item $% -X<$%> X<$FORMAT_PAGE_NUMBER> +=item DESTRUCT -The current page number of the currently selected output channel. -Used with formats. -(Mnemonic: % is page number in B<nroff>.) +Global destruction. -=item HANDLE->format_lines_per_page(EXPR) +=back -=item $FORMAT_LINES_PER_PAGE +Also note that there's no value for UNITCHECK-blocks. That's because +those are run for each compilation unit individually, and therefore is +not a global interpreter phase. -=item $= -X<$=> X<$FORMAT_LINES_PER_PAGE> +Not every program has to go through each of the possible phases, but +transition from one phase to another can only happen in the order +described in the above list. -The current page length (printable lines) of the currently selected -output channel. Default is 60. -Used with formats. -(Mnemonic: = has horizontal lines.) +An example of all of the phases Perl code can see: -=item HANDLE->format_lines_left(EXPR) + BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" } -=item $FORMAT_LINES_LEFT + INIT { print "init-time: ${^GLOBAL_PHASE}\n" } -=item $- -X<$-> X<$FORMAT_LINES_LEFT> + CHECK { print "check-time: ${^GLOBAL_PHASE}\n" } -The number of lines left on the page of the currently selected output -channel. -Used with formats. -(Mnemonic: lines_on_page - lines_printed.) + { + package Print::Phase; -=item @LAST_MATCH_START + sub new { + my ($class, $time) = @_; + return bless \$time, $class; + } -=item @- -X<@-> X<@LAST_MATCH_START> + sub DESTROY { + my $self = shift; + print "$$self: ${^GLOBAL_PHASE}\n"; + } + } -$-[0] is the offset of the start of the last successful match. -C<$-[>I<n>C<]> is the offset of the start of the substring matched by -I<n>-th subpattern, or undef if the subpattern did not match. + print "run-time: ${^GLOBAL_PHASE}\n"; -Thus after a match against $_, $& coincides with C<substr $_, $-[0], -$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n], -$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with -C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the last -matched subgroup in the last successful match. Contrast with -C<$#+>, the number of subgroups in the regular expression. Compare -with C<@+>. + my $runtime = Print::Phase->new( + "lexical variables are garbage collected before END" + ); -This array holds the offsets of the beginnings of the last -successful submatches in the currently active dynamic scope. -C<$-[0]> is the offset into the string of the beginning of the -entire match. The I<n>th element of this array holds the offset -of the I<n>th submatch, so C<$-[1]> is the offset where $1 -begins, C<$-[2]> the offset where $2 begins, and so on. + END { print "end-time: ${^GLOBAL_PHASE}\n" } -After a match against some variable $var: + our $destruct = Print::Phase->new( + "package variables are garbage collected after END" + ); -=over 5 +This will print out -=item C<$`> is the same as C<substr($var, 0, $-[0])> + compile-time: START + check-time: CHECK + init-time: INIT + run-time: RUN + lexical variables are garbage collected before END: RUN + end-time: END + package variables are garbage collected after END: DESTRUCT -=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> +This variable was added in Perl 5.14.0. -=item C<$'> is the same as C<substr($var, $+[0])> +=item $^H +X<$^H> -=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> +WARNING: This variable is strictly for internal use only. Its availability, +behavior, and contents are subject to change without notice. -=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> +This variable contains compile-time hints for the Perl interpreter. At the +end of compilation of a BLOCK the value of this variable is restored to the +value when the interpreter started to compile the BLOCK. -=item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])> +When perl begins to parse any block construct that provides a lexical scope +(e.g., eval body, required file, subroutine body, loop body, or conditional +block), the existing value of C<$^H> is saved, but its value is left unchanged. +When the compilation of the block is completed, it regains the saved value. +Between the points where its value is saved and restored, code that +executes within BEGIN blocks is free to change the value of C<$^H>. -=back +This behavior provides the semantic of lexical scoping, and is used in, +for instance, the C<use strict> pragma. -=item %- -X<%-> +The contents should be an integer; different bits of it are used for +different pragmatic flags. Here's an example: -Similar to C<%+>, this variable allows access to the named capture buffers -in the last successful match in the currently active dynamic scope. To -each capture buffer name found in the regular expression, it associates a -reference to an array containing the list of values captured by all -buffers with that name (should there be several of them), in the order -where they appear. + sub add_100 { $^H |= 0x100 } -Here's an example: + sub foo { + BEGIN { add_100() } + bar->baz($boon); + } - if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) { - foreach my $bufname (sort keys %-) { - my $ary = $-{$bufname}; - foreach my $idx (0..$#$ary) { - print "\$-{$bufname}[$idx] : ", - (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"), - "\n"; - } - } - } +Consider what happens during execution of the BEGIN block. At this point +the BEGIN block has already been compiled, but the body of C<foo()> is still +being compiled. The new value of C<$^H> will therefore be visible only while +the body of C<foo()> is being compiled. -would print out: +Substitution of C<BEGIN { add_100() }> block with: - $-{A}[0] : '1' - $-{A}[1] : '3' - $-{B}[0] : '2' - $-{B}[1] : '4' + BEGIN { require strict; strict->import('vars') } -The keys of the C<%-> hash correspond to all buffer names found in -the regular expression. +demonstrates how C<use strict 'vars'> is implemented. Here's a conditional +version of the same lexical pragma: -The behaviour of C<%-> is implemented via the -L<Tie::Hash::NamedCapture> module. + BEGIN { require strict; strict->import('vars') if $condition } -B<Note:> C<%-> and C<%+> are tied views into a common internal hash -associated with the last successful regular expression. Therefore mixing -iterative access to them via C<each> may have unpredictable results. -Likewise, if the last successful match changes, then the results may be -surprising. +This variable was added in Perl 5.003. -=item HANDLE->format_name(EXPR) +=item %^H +X<%^H> -=item $FORMAT_NAME +The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes it +useful for implementation of lexically scoped pragmas. See L<perlpragma>. -=item $~ -X<$~> X<$FORMAT_NAME> +This variable was added in Perl 5.6. -The name of the current report format for the currently selected output -channel. Default is the name of the filehandle. (Mnemonic: brother to -C<$^>.) +=item @INC +X<@INC> -=item HANDLE->format_top_name(EXPR) +The array C<@INC> contains the list of places that the C<do EXPR>, +C<require>, or C<use> constructs look for their library files. It +initially consists of the arguments to any B<-I> command-line +switches, followed by the default Perl library, probably +F</usr/local/lib/perl>, followed by ".", to represent the current +directory. ("." will not be appended if taint checks are enabled, +either by C<-T> or by C<-t>.) If you need to modify this at runtime, +you should use the C<use lib> pragma to get the machine-dependent +library properly loaded also: -=item $FORMAT_TOP_NAME + use lib '/mypath/libdir/'; + use SomeMod; -=item $^ -X<$^> X<$FORMAT_TOP_NAME> +You can also insert hooks into the file inclusion system by putting Perl +code directly into C<@INC>. Those hooks may be subroutine references, array +references or blessed objects. See L<perlfunc/require> for details. -The name of the current top-of-page format for the currently selected -output channel. Default is the name of the filehandle with _TOP -appended. (Mnemonic: points to top of page.) +=item %INC +X<%INC> -=item IO::Handle->format_line_break_characters EXPR +The hash C<%INC> contains entries for each filename included via the +C<do>, C<require>, or C<use> operators. The key is the filename +you specified (with module names converted to pathnames), and the +value is the location of the file found. The C<require> +operator uses this hash to determine whether a particular file has +already been included. -=item $FORMAT_LINE_BREAK_CHARACTERS +If the file was loaded via a hook (e.g. a subroutine reference, see +L<perlfunc/require> for a description of these hooks), this hook is +by default inserted into C<%INC> in place of a filename. Note, however, +that the hook may have set the C<%INC> entry by itself to provide some more +specific info. -=item $: -X<$:> X<FORMAT_LINE_BREAK_CHARACTERS> +=item $INPLACE_EDIT -The current set of characters after which a string may be broken to -fill continuation fields (starting with ^) in a format. Default is -S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in -poetry is a part of a line.) +=item $^I +X<$^I> X<$INPLACE_EDIT> -=item IO::Handle->format_formfeed EXPR +The current value of the inplace-edit extension. Use C<undef> to disable +inplace editing. -=item $FORMAT_FORMFEED +Mnemonic: value of B<-i> switch. -=item $^L -X<$^L> X<$FORMAT_FORMFEED> +=item $^M +X<$^M> -What formats output as a form feed. Default is \f. +By default, running out of memory is an untrappable, fatal error. +However, if suitably built, Perl can use the contents of C<$^M> +as an emergency memory pool after C<die()>ing. Suppose that your Perl +were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc. +Then -=item $ACCUMULATOR + $^M = 'a' x (1 << 16); -=item $^A -X<$^A> X<$ACCUMULATOR> +would allocate a 64K buffer for use in an emergency. See the +F<INSTALL> file in the Perl distribution for information on how to +add custom C compilation flags when compiling perl. To discourage casual +use of this advanced feature, there is no L<English|English> long name for +this variable. -The current value of the write() accumulator for format() lines. A format -contains formline() calls that put their result into C<$^A>. After -calling its format, write() prints out the contents of C<$^A> and empties. -So you never really see the contents of C<$^A> unless you call -formline() yourself and then look at it. See L<perlform> and -L<perlfunc/formline()>. +This variable was added in Perl 5.004. -=item $CHILD_ERROR +=item $OSNAME -=item $? -X<$?> X<$CHILD_ERROR> +=item $^O +X<$^O> X<$OSNAME> -The status returned by the last pipe close, backtick (C<``>) command, -successful call to wait() or waitpid(), or from the system() -operator. This is just the 16-bit status word returned by the -traditional Unix wait() system call (or else is made up to look like it). Thus, the -exit value of the subprocess is really (C<<< $? >> 8 >>>), and -C<$? & 127> gives which signal, if any, the process died from, and -C<$? & 128> reports whether there was a core dump. (Mnemonic: -similar to B<sh> and B<ksh>.) +The name of the operating system under which this copy of Perl was +built, as determined during the configuration process. For examples +see L<perlport/PLATFORMS>. -Additionally, if the C<h_errno> variable is supported in C, its value -is returned via $? if any C<gethost*()> function fails. +The value is identical to C<$Config{'osname'}>. See also L<Config> +and the B<-V> command-line switch documented in L<perlrun>. -If you have installed a signal handler for C<SIGCHLD>, the -value of C<$?> will usually be wrong outside that handler. +In Windows platforms, C<$^O> is not very helpful: since it is always +C<MSWin32>, it doesn't tell the difference between +95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or +Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish +between the variants. -Inside an C<END> subroutine C<$?> contains the value that is going to be -given to C<exit()>. You can modify C<$?> in an C<END> subroutine to -change the exit status of your program. For example: +This variable was added in Perl 5.003. - END { - $? = 1 if $? == 255; # die would make it 255 - } +=item ${^OPEN} +X<${^OPEN}> -Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the -actual VMS exit status, instead of the default emulation of POSIX -status; see L<perlvms/$?> for details. +An internal variable used by PerlIO. A string in two parts, separated +by a C<\0> byte, the first part describes the input layers, the second +part describes the output layers. -Also see L<Error Indicators>. +This variable was added in Perl 5.8.2. -=item ${^CHILD_ERROR_NATIVE} -X<$^CHILD_ERROR_NATIVE> +=item $PERLDB -The native status returned by the last pipe close, backtick (C<``>) -command, successful call to wait() or waitpid(), or from the system() -operator. On POSIX-like systems this value can be decoded with the -WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG -and WIFCONTINUED functions provided by the L<POSIX> module. +=item $^P +X<$^P> X<$PERLDB> -Under VMS this reflects the actual VMS exit status; i.e. it is the same -as $? when the pragma C<use vmsish 'status'> is in effect. +The internal variable for debugging support. The meanings of the +various bits are subject to change, but currently indicate: -=item ${^ENCODING} -X<$^ENCODING> +=over 6 -The I<object reference> to the Encode object that is used to convert -the source code to Unicode. Thanks to this variable your perl script -does not have to be written in UTF-8. Default is I<undef>. The direct -manipulation of this variable is highly discouraged. +=item 0x01 -=item $OS_ERROR +Debug subroutine enter/exit. -=item $ERRNO +=item 0x02 -=item $! -X<$!> X<$ERRNO> X<$OS_ERROR> +Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for each +statement executed. Also causes saving source code lines (like 0x400). -If used numerically, yields the current value of the C C<errno> -variable, or in other words, if a system or library call fails, it -sets this variable. This means that the value of C<$!> is meaningful -only I<immediately> after a B<failure>: +=item 0x04 - if (open my $fh, "<", $filename) { - # Here $! is meaningless. - ... - } else { - # ONLY here is $! meaningful. +Switch off optimizations. + +=item 0x08 + +Preserve more data for future interactive inspections. + +=item 0x10 + +Keep info about source lines on which a subroutine is defined. + +=item 0x20 + +Start with single-step on. + +=item 0x40 + +Use subroutine address instead of name when reporting. + +=item 0x80 + +Report C<goto &subroutine> as well. + +=item 0x100 + +Provide informative "file" names for evals based on the place they were compiled. + +=item 0x200 + +Provide informative names to anonymous subroutines based on the place they +were compiled. + +=item 0x400 + +Save source code lines into C<@{"_<$filename"}>. + +=back + +Some bits may be relevant at compile-time only, some at +run-time only. This is a new mechanism and the details may change. +See also L<perldebguts>. + +=item %SIG +X<%SIG> + +The hash C<%SIG> contains signal handlers for signals. For example: + + sub handler { # 1st argument is signal name + my($sig) = @_; + print "Caught a SIG$sig--shutting down\n"; + close(LOG); + exit(0); + } + + $SIG{'INT'} = \&handler; + $SIG{'QUIT'} = \&handler; ... - # Already here $! might be meaningless. - } - # Since here we might have either success or failure, - # here $! is meaningless. + $SIG{'INT'} = 'DEFAULT'; # restore default action + $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT -In the above I<meaningless> stands for anything: zero, non-zero, -C<undef>. A successful system or library call does B<not> set -the variable to zero. +Using a value of C<'IGNORE'> usually has the effect of ignoring the +signal, except for the C<CHLD> signal. See L<perlipc> for more about +this special case. -If used as a string, yields the corresponding system error string. -You can assign a number to C<$!> to set I<errno> if, for instance, -you want C<"$!"> to return the string for error I<n>, or you want -to set the exit value for the die() operator. (Mnemonic: What just -went bang?) +Here are some other examples: -Also see L<Error Indicators>. + $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) + $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber + $SIG{"PIPE"} = *Plumber; # somewhat esoteric + $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? -=item %OS_ERROR +Be sure not to use a bareword as the name of a signal handler, +lest you inadvertently call it. -=item %ERRNO +If your system has the C<sigaction()> function then signal handlers +are installed using it. This means you get reliable signal handling. -=item %! -X<%!> +The default delivery policy of signals changed in Perl 5.8.0 from +immediate (also known as "unsafe") to deferred, also known as "safe +signals". See L<perlipc> for more information. -Each element of C<%!> has a true value only if C<$!> is set to that -value. For example, C<$!{ENOENT}> is true if and only if the current -value of C<$!> is C<ENOENT>; that is, if the most recent error was -"No such file or directory" (or its moral equivalent: not all operating -systems give that exact error, and certainly not all languages). -To check if a particular key is meaningful on your system, use -C<exists $!{the_key}>; for a list of legal keys, use C<keys %!>. -See L<Errno> for more information, and also see above for the -validity of C<$!>. +Certain internal hooks can be also set using the C<%SIG> hash. The +routine indicated by C<$SIG{__WARN__}> is called when a warning +message is about to be printed. The warning message is passed as the +first argument. The presence of a C<__WARN__> hook causes the +ordinary printing of warnings to C<STDERR> to be suppressed. You can +use this to save warnings in a variable, or turn warnings into fatal +errors, like this: -=item $EXTENDED_OS_ERROR + local $SIG{__WARN__} = sub { die $_[0] }; + eval $proggie; -=item $^E -X<$^E> X<$EXTENDED_OS_ERROR> +As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can +disable warnings using the empty subroutine: -Error information specific to the current operating system. At -the moment, this differs from C<$!> under only VMS, OS/2, and Win32 -(and for MacPerl). On all other platforms, C<$^E> is always just -the same as C<$!>. + local $SIG{__WARN__} = sub {}; -Under VMS, C<$^E> provides the VMS status value from the last -system error. This is more specific information about the last -system error than that provided by C<$!>. This is particularly -important when C<$!> is set to B<EVMSERR>. +The routine indicated by C<$SIG{__DIE__}> is called when a fatal +exception is about to be thrown. The error message is passed as the +first argument. When a C<__DIE__> hook routine returns, the exception +processing continues as it would have in the absence of the hook, +unless the hook routine itself exits via a C<goto>, a loop exit, or a +C<die()>. The C<__DIE__> handler is explicitly disabled during the +call, so that you can die from a C<__DIE__> handler. Similarly for +C<__WARN__>. -Under OS/2, C<$^E> is set to the error code of the last call to -OS/2 API either via CRT, or directly from perl. +Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called +even inside an C<eval()>. Do not use this to rewrite a pending +exception in C<$@>, or as a bizarre substitute for overriding +C<CORE::GLOBAL::die()>. This strange action at a distance may be fixed +in a future release so that C<$SIG{__DIE__}> is only called if your +program is about to exit, as was the original intent. Any other use is +deprecated. + +C<__DIE__>/C<__WARN__> handlers are very special in one respect: they +may be called to report (probable) errors found by the parser. In such +a case the parser may be in inconsistent state, so any attempt to +evaluate Perl code from such a handler will probably result in a +segfault. This means that warnings or errors that result from parsing +Perl should be used with extreme caution, like this: + + require Carp if defined $^S; + Carp::confess("Something wrong") if defined &Carp::confess; + die "Something wrong, but could not load Carp to give backtrace... + To see backtrace try starting Perl with -MCarp switch"; + +Here the first line will load C<Carp> I<unless> it is the parser who +called the handler. The second line will print backtrace and die if +C<Carp> was available. The third line will be executed only if C<Carp> was +not available. -Under Win32, C<$^E> always returns the last error information -reported by the Win32 call C<GetLastError()> which describes -the last error from within the Win32 API. Most Win32-specific -code will report errors via C<$^E>. ANSI C and Unix-like calls -set C<errno> and so most portable Perl code will report errors -via C<$!>. +Having to even think about the C<$^S> variable in your exception +handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented +invites grievous and difficult to track down errors. Avoid it +and use an C<END{}> or CORE::GLOBAL::die override instead. -Caveats mentioned in the description of C<$!> generally apply to -C<$^E>, also. (Mnemonic: Extra error explanation.) +See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and +L<warnings> for additional information. -Also see L<Error Indicators>. +=item $BASETIME -=item $EVAL_ERROR +=item $^T +X<$^T> X<$BASETIME> -=item $@ -X<$@> X<$EVAL_ERROR> +The time at which the program began running, in seconds since the +epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, +and B<-C> filetests are based on this value. -The Perl syntax error message from the last eval() operator. -If $@ is the null string, the last eval() parsed and executed -correctly (although the operations you invoked may have failed in the -normal fashion). (Mnemonic: Where was the syntax error "at"?) +=item ${^TAINT} +X<${^TAINT}> -Warning messages are not collected in this variable. You can, -however, set up a routine to process warnings by setting C<$SIG{__WARN__}> -as described below. +Reflects if taint mode is on or off. 1 for on (the program was run with +B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with +B<-t> or B<-TU>). -Also see L<Error Indicators>. +This variable is read-only. -=item $PROCESS_ID +This variable was added in Perl 5.8. -=item $PID +=item ${^UNICODE} +X<${^UNICODE}> -=item $$ -X<$$> X<$PID> X<$PROCESS_ID> +Reflects certain Unicode settings of Perl. See L<perlrun> +documentation for the C<-C> switch for more information about +the possible values. -The process number of the Perl running this script. You should -consider this variable read-only, although it will be altered -across fork() calls. (Mnemonic: same as shells.) +This variable is set during Perl startup and is thereafter read-only. -Note for Linux users: on Linux, the C functions C<getpid()> and -C<getppid()> return different values from different threads. In order to -be portable, this behavior is not reflected by C<$$>, whose value remains -consistent across threads. If you want to call the underlying C<getpid()>, -you may use the CPAN module C<Linux::Pid>. +This variable was added in Perl 5.8.2. -=item $REAL_USER_ID +=item ${^UTF8CACHE} +X<${^UTF8CACHE}> -=item $UID +This variable controls the state of the internal UTF-8 offset caching code. +1 for on (the default), 0 for off, -1 to debug the caching code by checking +all its results against linear scans, and panicking on any discrepancy. -=item $< -X<< $< >> X<$UID> X<$REAL_USER_ID> +This variable was added in Perl 5.8.9. -The real uid of this process. (Mnemonic: it's the uid you came I<from>, -if you're running setuid.) You can change both the real uid and -the effective uid at the same time by using POSIX::setuid(). Since -changes to $< require a system call, check $! after a change attempt to -detect any possible errors. +=item ${^UTF8LOCALE} +X<${^UTF8LOCALE}> -=item $EFFECTIVE_USER_ID +This variable indicates whether a UTF-8 locale was detected by perl at +startup. This information is used by perl when it's in +adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line +switch); see L<perlrun> for more info on this. -=item $EUID +This variable was added in Perl 5.8.8. -=item $> -X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID> +=item $PERL_VERSION -The effective uid of this process. Example: +=item $^V +X<$^V> X<$PERL_VERSION> - $< = $>; # set real to effective uid - ($<,$>) = ($>,$<); # swap real and effective uid +The revision, version, and subversion of the Perl interpreter, +represented as a C<version> object. -You can change both the effective uid and the real uid at the same -time by using POSIX::setuid(). Changes to $> require a check to $! -to detect any possible errors after an attempted change. +This variable first appeared in perl 5.6.0; earlier versions of perl +will see an undefined value. Before perl 5.10.0 C<$^V> was represented +as a v-string. -(Mnemonic: it's the uid you went I<to>, if you're running setuid.) -C<< $< >> and C<< $> >> can be swapped only on machines -supporting setreuid(). +C<$^V> can be used to determine whether the Perl interpreter executing +a script is in the right range of versions. For example: -=item $REAL_GROUP_ID + warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1 -=item $GID +To convert C<$^V> into its string representation use C<sprintf()>'s +C<"%vd"> conversion: -=item $( -X<$(> X<$GID> X<$REAL_GROUP_ID> + printf "version is v%vd\n", $^V; # Perl's version -The real gid of this process. If you are on a machine that supports -membership in multiple groups simultaneously, gives a space separated -list of groups you are in. The first number is the one returned by -getgid(), and the subsequent ones by getgroups(), one of which may be -the same as the first number. +See the documentation of C<use VERSION> and C<require VERSION> +for a convenient way to fail if the running Perl interpreter is too old. -However, a value assigned to C<$(> must be a single number used to -set the real gid. So the value given by C<$(> should I<not> be assigned -back to C<$(> without being forced numeric, such as by adding zero. Note -that this is different to the effective gid (C<$)>) which does take a -list. +See also C<$]> for an older representation of the Perl version. -You can change both the real gid and the effective gid at the same -time by using POSIX::setgid(). Changes to $( require a check to $! -to detect any possible errors after an attempted change. +This variable was added in Perl 5.6. -(Mnemonic: parentheses are used to I<group> things. The real gid is the -group you I<left>, if you're running setgid.) +Mnemonic: use ^V for Version Control. -=item $EFFECTIVE_GROUP_ID +=item ${^WIN32_SLOPPY_STAT} +X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl> -=item $EGID +If this variable is set to a true value, then C<stat()> on Windows will +not try to open the file. This means that the link count cannot be +determined and file attributes may be out of date if additional +hardlinks to the file exist. On the other hand, not opening the file +is considerably faster, especially for files on network drives. -=item $) -X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID> +This variable could be set in the F<sitecustomize.pl> file to +configure the local Perl installation to use "sloppy" C<stat()> by +default. See the documentation for B<-f> in +L<perlrun|perlrun/"Command Switches"> for more information about site +customization. -The effective gid of this process. If you are on a machine that -supports membership in multiple groups simultaneously, gives a space -separated list of groups you are in. The first number is the one -returned by getegid(), and the subsequent ones by getgroups(), one of -which may be the same as the first number. +This variable was added in Perl 5.10. -Similarly, a value assigned to C<$)> must also be a space-separated -list of numbers. The first number sets the effective gid, and -the rest (if any) are passed to setgroups(). To get the effect of an -empty list for setgroups(), just repeat the new effective gid; that is, -to force an effective gid of 5 and an effectively empty setgroups() -list, say C< $) = "5 5" >. +=item $EXECUTABLE_NAME -You can change both the effective gid and the real gid at the same -time by using POSIX::setgid() (use only a single numeric argument). -Changes to $) require a check to $! to detect any possible errors -after an attempted change. +=item $^X +X<$^X> X<$EXECUTABLE_NAME> -(Mnemonic: parentheses are used to I<group> things. The effective gid -is the group that's I<right> for you, if you're running setgid.) +The name used to execute the current copy of Perl, from C's +C<argv[0]> or (where supported) F</proc/self/exe>. -C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on -machines that support the corresponding I<set[re][ug]id()> routine. C<$(> -and C<$)> can be swapped only on machines supporting setregid(). +Depending on the host operating system, the value of C<$^X> may be +a relative or absolute pathname of the perl program file, or may +be the string used to invoke perl but not the pathname of the +perl program file. Also, most operating systems permit invoking +programs that are not in the PATH environment variable, so there +is no guarantee that the value of C<$^X> is in PATH. For VMS, the +value may or may not include a version number. -=item $PROGRAM_NAME +You usually can use the value of C<$^X> to re-invoke an independent +copy of the same perl that is currently running, e.g., -=item $0 -X<$0> X<$PROGRAM_NAME> + @first_run = `$^X -le "print int rand 100 for 1..100"`; -Contains the name of the program being executed. +But recall that not all operating systems support forking or +capturing of the output of commands, so this complex statement +may not be portable. -On some (read: not all) operating systems assigning to C<$0> modifies -the argument area that the C<ps> program sees. On some platforms you -may have to use special C<ps> options or a different C<ps> to see the -changes. Modifying the $0 is more useful as a way of indicating the -current program state than it is for hiding the program you're -running. (Mnemonic: same as B<sh> and B<ksh>.) +It is not safe to use the value of C<$^X> as a path name of a file, +as some operating systems that have a mandatory suffix on +executable files do not require use of the suffix when invoking +a command. To convert the value of C<$^X> to a path name, use the +following statements: -Note that there are platform specific limitations on the maximum -length of C<$0>. In the most extreme case it may be limited to the -space occupied by the original C<$0>. + # Build up a set of file names (not command names). + use Config; + my $this_perl = $^X; + if ($^O ne 'VMS') { + $this_perl .= $Config{_exe} + unless $this_perl =~ m/$Config{_exe}$/i; + } -In some platforms there may be arbitrary amount of padding, for -example space characters, after the modified name as shown by C<ps>. -In some platforms this padding may extend all the way to the original -length of the argument area, no matter what you do (this is the case -for example with Linux 2.2). +Because many operating systems permit anyone with read access to +the Perl program file to make a copy of it, patch the copy, and +then execute the copy, the security-conscious Perl programmer +should take care to invoke the installed copy of perl, not the +copy referenced by C<$^X>. The following statements accomplish +this goal, and produce a pathname that can be invoked as a +command or referenced as a file. -Note for BSD users: setting C<$0> does not completely remove "perl" -from the ps(1) output. For example, setting C<$0> to C<"foobar"> may -result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix -and the " (perl)" suffix are shown depends on your exact BSD variant -and version). This is an operating system feature, Perl cannot help it. + use Config; + my $secure_perl_path = $Config{perlpath}; + if ($^O ne 'VMS') { + $secure_perl_path .= $Config{_exe} + unless $secure_perl_path =~ m/$Config{_exe}$/i; + } -In multithreaded scripts Perl coordinates the threads so that any -thread may modify its copy of the C<$0> and the change becomes visible -to ps(1) (assuming the operating system plays along). Note that -the view of C<$0> the other threads have will not change since they -have their own copies of it. +=back -If the program has been given to perl via the switches C<-e> or C<-E>, -C<$0> will contain the string C<"-e">. +=head2 Variables related to regular expressions -=item $[ -X<$[> +Most of the special variables related to regular expressions are side +effects. Perl sets these variables when it has a successful match, so +you should check the match result before using them. For instance: -The index of the first element in an array, and of the first character -in a substring. Default is 0, but you could theoretically set it -to 1 to make Perl behave more like B<awk> (or Fortran) when -subscripting and when evaluating the index() and substr() functions. -(Mnemonic: [ begins subscripts.) + if( /P(A)TT(ER)N/ ) { + print "I found $1 and $2\n"; + } -As of release 5 of Perl, assignment to C<$[> is treated as a compiler -directive, and cannot influence the behavior of any other file. -(That's why you can only assign compile-time constants to it.) Its -use is deprecated, and by default will trigger a warning. +These variables are read-only and dynamically-scoped, unless we note +otherwise. -Note that, unlike other compile-time directives (such as L<strict>), -assignment to C<$[> can be seen from outer lexical scopes in the same file. -However, you can use local() on it to strictly bind its value to a -lexical block. +The dynamic nature of the regular expression variables means that +their value is limited to the block that they are in, as demonstrated +by this bit of code: -=item $] -X<$]> + my $outer = 'Wallace and Grommit'; + my $inner = 'Mutt and Jeff'; -The version + patchlevel / 1000 of the Perl interpreter. This variable -can be used to determine whether the Perl interpreter executing a -script is in the right range of versions. (Mnemonic: Is this version -of perl in the right bracket?) Example: + my $pattern = qr/(\S+) and (\S+)/; - warn "No checksumming!\n" if $] < 3.019; + sub show_n { print "\$1 is $1; \$2 is $2\n" } -See also the documentation of C<use VERSION> and C<require VERSION> -for a convenient way to fail if the running Perl interpreter is too old. + { + OUTER: + show_n() if $outer =~ m/$pattern/; -The floating point representation can sometimes lead to inaccurate -numeric comparisons. See C<$^V> for a more modern representation of -the Perl version that allows accurate string comparisons. + INNER: { + show_n() if $inner =~ m/$pattern/; + } -=item $COMPILING + show_n(); + } -=item $^C -X<$^C> X<$COMPILING> +The output shows that while in the C<OUTER> block, the values of C<$1> +and C<$2> are from the match against C<$outer>. Inside the C<INNER> +block, the values of C<$1> and C<$2> are from the match against +C<$inner>, but only until the end of the block (i.e. the dynamic +scope). After the C<INNER> block completes, the values of C<$1> and +C<$2> return to the values for the match against C<$outer> even though +we have not made another match: -The current value of the flag associated with the B<-c> switch. -Mainly of use with B<-MO=...> to allow code to alter its behavior -when being compiled, such as for example to AUTOLOAD at compile -time rather than normal, deferred loading. Setting -C<$^C = 1> is similar to calling C<B::minus_c>. + $1 is Wallace; $2 is Grommit + $1 is Mutt; $2 is Jeff + $1 is Wallace; $2 is Grommit -=item $DEBUGGING +Due to an unfortunate accident of Perl's implementation, C<use +English> imposes a considerable performance penalty on all regular +expression matches in a program because it uses the C<$`>, C<$&>, and +C<$'>, regardless of whether they occur in the scope of C<use +English>. For that reason, saying C<use English> in libraries is +strongly discouraged unless you import it without the match variables: -=item $^D -X<$^D> X<$DEBUGGING> + use English '-no_match_vars' -The current value of the debugging flags. (Mnemonic: value of B<-D> -switch.) May be read or set. Like its command-line equivalent, you can use -numeric or symbolic values, eg C<$^D = 10> or C<$^D = "st">. +The C<Devel::NYTProf> and C<Devel::FindAmpersand> +modules can help you find uses of these +problematic match variables in your code. -=item ${^RE_DEBUG_FLAGS} +Since Perl 5.10, you can use the C</p> match operator flag and the +C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead +so you only suffer the performance penalties. -The current value of the regex debugging flags. Set to 0 for no debug output -even when the re 'debug' module is loaded. See L<re> for details. +=over 8 -=item ${^RE_TRIE_MAXBUF} +=item $<I<digits>> ($1, $2, ...) +X<$1> X<$2> X<$3> -Controls how certain regex optimisations are applied and how much memory they -utilize. This value by default is 65536 which corresponds to a 512kB temporary -cache. Set this to a higher value to trade memory for speed when matching -large alternations. Set it to a lower value if you want the optimisations to -be as conservative of memory as possible but still occur, and set it to a -negative value to prevent the optimisation and conserve the most memory. -Under normal situations this variable should be of no interest to you. +Contains the subpattern from the corresponding set of capturing +parentheses from the last successful pattern match, not counting patterns +matched in nested blocks that have been exited already. -=item $SYSTEM_FD_MAX +These variables are read-only and dynamically-scoped. -=item $^F -X<$^F> X<$SYSTEM_FD_MAX> +Mnemonic: like \digits. -The maximum system file descriptor, ordinarily 2. System file -descriptors are passed to exec()ed processes, while higher file -descriptors are not. Also, during an open(), system file descriptors are -preserved even if the open() fails. (Ordinary file descriptors are -closed before the open() is attempted.) The close-on-exec -status of a file descriptor will be decided according to the value of -C<$^F> when the corresponding file, pipe, or socket was opened, not the -time of the exec(). +=item $MATCH -=item $^H +=item $& +X<$&> X<$MATCH> -WARNING: This variable is strictly for internal use only. Its availability, -behavior, and contents are subject to change without notice. +The string matched by the last successful pattern match (not counting +any matches hidden within a BLOCK or C<eval()> enclosed by the current +BLOCK). -This variable contains compile-time hints for the Perl interpreter. At the -end of compilation of a BLOCK the value of this variable is restored to the -value when the interpreter started to compile the BLOCK. +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. To avoid this +penalty, you can extract the same substring by using L</@->. Starting +with Perl 5.10, you can use the </p> match flag and the C<${^MATCH}> +variable to do the same thing for particular match operations. -When perl begins to parse any block construct that provides a lexical scope -(e.g., eval body, required file, subroutine body, loop body, or conditional -block), the existing value of $^H is saved, but its value is left unchanged. -When the compilation of the block is completed, it regains the saved value. -Between the points where its value is saved and restored, code that -executes within BEGIN blocks is free to change the value of $^H. +This variable is read-only and dynamically-scoped. -This behavior provides the semantic of lexical scoping, and is used in, -for instance, the C<use strict> pragma. +Mnemonic: like C<&> in some editors. -The contents should be an integer; different bits of it are used for -different pragmatic flags. Here's an example: +=item ${^MATCH} +X<${^MATCH}> - sub add_100 { $^H |= 0x100 } +This is similar to C<$&> (C<$MATCH>) except that it does not incur the +performance penalty associated with that variable, and is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C</p> modifier. - sub foo { - BEGIN { add_100() } - bar->baz($boon); - } +This variable was added in Perl 5.10. -Consider what happens during execution of the BEGIN block. At this point -the BEGIN block has already been compiled, but the body of foo() is still -being compiled. The new value of $^H will therefore be visible only while -the body of foo() is being compiled. +This variable is read-only and dynamically-scoped. -Substitution of the above BEGIN block with: +=item $PREMATCH - BEGIN { require strict; strict->import('vars') } +=item $` +X<$`> X<$PREMATCH> X<${^PREMATCH}> -demonstrates how C<use strict 'vars'> is implemented. Here's a conditional -version of the same lexical pragma: +The string preceding whatever was matched by the last successful +pattern match, not counting any matches hidden within a BLOCK or C<eval> +enclosed by the current BLOCK. - BEGIN { require strict; strict->import('vars') if $condition } +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. To avoid this +penalty, you can extract the same substring by using L</@->. Starting +with Perl 5.10, you can use the </p> match flag and the +C<${^PREMATCH}> variable to do the same thing for particular match +operations. -=item %^H +This variable is read-only and dynamically-scoped. -The %^H hash provides the same scoping semantic as $^H. This makes it -useful for implementation of lexically scoped pragmas. See L<perlpragma>. +Mnemonic: C<`> often precedes a quoted string. -=item $INPLACE_EDIT +=item ${^PREMATCH} +X<$`> X<${^PREMATCH}> -=item $^I -X<$^I> X<$INPLACE_EDIT> +This is similar to C<$`> ($PREMATCH) except that it does not incur the +performance penalty associated with that variable, and is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C</p> modifier. -The current value of the inplace-edit extension. Use C<undef> to disable -inplace editing. (Mnemonic: value of B<-i> switch.) +This variable was added in Perl 5.10 -=item $^M -X<$^M> +This variable is read-only and dynamically-scoped. -By default, running out of memory is an untrappable, fatal error. -However, if suitably built, Perl can use the contents of C<$^M> -as an emergency memory pool after die()ing. Suppose that your Perl -were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc. -Then +=item $POSTMATCH - $^M = 'a' x (1 << 16); +=item $' +X<$'> X<$POSTMATCH> X<${^POSTMATCH}> X<@-> -would allocate a 64K buffer for use in an emergency. See the -F<INSTALL> file in the Perl distribution for information on how to -add custom C compilation flags when compiling perl. To discourage casual -use of this advanced feature, there is no L<English|English> long name for -this variable. +The string following whatever was matched by the last successful +pattern match (not counting any matches hidden within a BLOCK or C<eval()> +enclosed by the current BLOCK). Example: -=item $OSNAME + local $_ = 'abcdefghi'; + /def/; + print "$`:$&:$'\n"; # prints abc:def:ghi -=item $^O -X<$^O> X<$OSNAME> +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. +To avoid this penalty, you can extract the same substring by +using L</@->. Starting with Perl 5.10, you can use the </p> match flag +and the C<${^POSTMATCH}> variable to do the same thing for particular +match operations. -The name of the operating system under which this copy of Perl was -built, as determined during the configuration process. For examples -see L<perlport/PLATFORMS>. +This variable is read-only and dynamically-scoped. -The value is identical to C<$Config{'osname'}>. See also L<Config> -and the B<-V> command-line switch documented in L<perlrun>. +Mnemonic: C<'> often follows a quoted string. -In Windows platforms, $^O is not very helpful: since it is always -C<MSWin32>, it doesn't tell the difference between -95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or -Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish -between the variants. +=item ${^POSTMATCH} +X<${^POSTMATCH}> X<$'> X<$POSTMATCH> -=item ${^OPEN} +This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the +performance penalty associated with that variable, and is only guaranteed +to return a defined value when the pattern was compiled or executed with +the C</p> modifier. -An internal variable used by PerlIO. A string in two parts, separated -by a C<\0> byte, the first part describes the input layers, the second -part describes the output layers. +This variable was added in Perl 5.10. -=item $PERLDB +This variable is read-only and dynamically-scoped. -=item $^P -X<$^P> X<$PERLDB> +=item $LAST_PAREN_MATCH -The internal variable for debugging support. The meanings of the -various bits are subject to change, but currently indicate: +=item $+ +X<$+> X<$LAST_PAREN_MATCH> -=over 6 +The text matched by the last bracket of the last successful search pattern. +This is useful if you don't know which one of a set of alternative patterns +matched. For example: -=item 0x01 + /Version: (.*)|Revision: (.*)/ && ($rev = $+); -Debug subroutine enter/exit. +This variable is read-only and dynamically-scoped. -=item 0x02 +Mnemonic: be positive and forward looking. -Line-by-line debugging. Causes DB::DB() subroutine to be called for each -statement executed. Also causes saving source code lines (like 0x400). +=item $LAST_SUBMATCH_RESULT -=item 0x04 +=item $^N +X<$^N> X<$LAST_SUBMATCH_RESULT> -Switch off optimizations. +The text matched by the used group most-recently closed (i.e. the group +with the rightmost closing parenthesis) of the last successful search +pattern. -=item 0x08 +This is primarily used inside C<(?{...})> blocks for examining text +recently matched. For example, to effectively capture text to a variable +(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with -Preserve more data for future interactive inspections. + (?:(...)(?{ $var = $^N })) -=item 0x10 +By setting and then using C<$var> in this way relieves you from having to +worry about exactly which numbered set of parentheses they are. -Keep info about source lines on which a subroutine is defined. +This variable was added in Perl 5.8. -=item 0x20 +Mnemonic: the (possibly) Nested parenthesis that most recently closed. -Start with single-step on. +=item @LAST_MATCH_END -=item 0x40 +=item @+ +X<@+> X<@LAST_MATCH_END> -Use subroutine address instead of name when reporting. +This array holds the offsets of the ends of the last successful +submatches in the currently active dynamic scope. C<$+[0]> is +the offset into the string of the end of the entire match. This +is the same value as what the C<pos> function returns when called +on the variable that was matched against. The I<n>th element +of this array holds the offset of the I<n>th submatch, so +C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset +past where C<$2> ends, and so on. You can use C<$#+> to determine +how many subgroups were in the last successful match. See the +examples given for the C<@-> variable. -=item 0x80 +This variable was added in Perl 5.6. -Report C<goto &subroutine> as well. +=item %LAST_PAREN_MATCH -=item 0x100 +=item %+ +X<%+> X<%LAST_PAREN_MATCH> -Provide informative "file" names for evals based on the place they were compiled. +Similar to C<@+>, the C<%+> hash allows access to the named capture +buffers, should they exist, in the last successful match in the +currently active dynamic scope. -=item 0x200 +For example, C<$+{foo}> is equivalent to C<$1> after the following match: -Provide informative names to anonymous subroutines based on the place they -were compiled. + 'foo' =~ /(?<foo>foo)/; -=item 0x400 +The keys of the C<%+> hash list only the names of buffers that have +captured (and that are thus associated to defined values). -Save source code lines into C<@{"_<$filename"}>. +The underlying behaviour of C<%+> is provided by the +L<Tie::Hash::NamedCapture> module. + +B<Note:> C<%-> and C<%+> are tied views into a common internal hash +associated with the last successful regular expression. Therefore mixing +iterative access to them via C<each> may have unpredictable results. +Likewise, if the last successful match changes, then the results may be +surprising. + +This variable was added in Perl 5.10. + +This variable is read-only and dynamically-scoped. + +=item @LAST_MATCH_START + +=item @- +X<@-> X<@LAST_MATCH_START> + +C<$-[0]> is the offset of the start of the last successful match. +C<$-[>I<n>C<]> is the offset of the start of the substring matched by +I<n>-th subpattern, or undef if the subpattern did not match. + +Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0], +$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n], +$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with +C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the last +matched subgroup in the last successful match. Contrast with +C<$#+>, the number of subgroups in the regular expression. Compare +with C<@+>. + +This array holds the offsets of the beginnings of the last +successful submatches in the currently active dynamic scope. +C<$-[0]> is the offset into the string of the beginning of the +entire match. The I<n>th element of this array holds the offset +of the I<n>th submatch, so C<$-[1]> is the offset where C<$1> +begins, C<$-[2]> the offset where C<$2> begins, and so on. + +After a match against some variable C<$var>: + +=over 5 + +=item C<$`> is the same as C<substr($var, 0, $-[0])> + +=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> + +=item C<$'> is the same as C<substr($var, $+[0])> + +=item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> + +=item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> + +=item C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])> =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>. +This variable was added in Perl 5.6. -=item $LAST_REGEXP_CODE_RESULT +=item %LAST_MATCH_START -=item $^R -X<$^R> X<$LAST_REGEXP_CODE_RESULT> +=item %- +X<%-> X<%LAST_MATCH_START> -The result of evaluation of the last successful C<(?{ code })> -regular expression assertion (see L<perlre>). May be written to. +Similar to C<%+>, this variable allows access to the named capture groups +in the last successful match in the currently active dynamic scope. To +each capture group name found in the regular expression, it associates a +reference to an array containing the list of values captured by all +buffers with that name (should there be several of them), in the order +where they appear. -=item $EXCEPTIONS_BEING_CAUGHT +Here's an example: -=item $^S -X<$^S> X<$EXCEPTIONS_BEING_CAUGHT> + if ('1234' =~ /(?<A>1)(?<B>2)(?<A>3)(?<B>4)/) { + foreach my $bufname (sort keys %-) { + my $ary = $-{$bufname}; + foreach my $idx (0..$#$ary) { + print "\$-{$bufname}[$idx] : ", + (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"), + "\n"; + } + } + } -Current state of the interpreter. +would print out: - $^S State - --------- ------------------- - undef Parsing module/eval - true (1) Executing an eval - false (0) Otherwise + $-{A}[0] : '1' + $-{A}[1] : '3' + $-{B}[0] : '2' + $-{B}[1] : '4' -The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers. +The keys of the C<%-> hash correspond to all buffer names found in +the regular expression. -=item $BASETIME +The behaviour of C<%-> is implemented via the +L<Tie::Hash::NamedCapture> module. -=item $^T -X<$^T> X<$BASETIME> +B<Note:> C<%-> and C<%+> are tied views into a common internal hash +associated with the last successful regular expression. Therefore mixing +iterative access to them via C<each> may have unpredictable results. +Likewise, if the last successful match changes, then the results may be +surprising. -The time at which the program began running, in seconds since the -epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, -and B<-C> filetests are based on this value. +This variable was added in Perl 5.10 -=item ${^TAINT} +This variable is read-only and dynamically-scoped. -Reflects if taint mode is on or off. 1 for on (the program was run with -B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with -B<-t> or B<-TU>). This variable is read-only. +=item $LAST_REGEXP_CODE_RESULT -=item ${^UNICODE} +=item $^R +X<$^R> X<$LAST_REGEXP_CODE_RESULT> -Reflects certain Unicode settings of Perl. See L<perlrun> -documentation for the C<-C> switch for more information about -the possible values. This variable is set during Perl startup -and is thereafter read-only. +The result of evaluation of the last successful C<(?{ code })> +regular expression assertion (see L<perlre>). May be written to. -=item ${^UTF8CACHE} +This variable was added in Perl 5.005. -This variable controls the state of the internal UTF-8 offset caching code. -1 for on (the default), 0 for off, -1 to debug the caching code by checking -all its results against linear scans, and panicking on any discrepancy. +=item ${^RE_DEBUG_FLAGS} +X<${^RE_DEBUG_FLAGS}> -=item ${^UTF8LOCALE} +The current value of the regex debugging flags. Set to 0 for no debug output +even when the C<re 'debug'> module is loaded. See L<re> for details. -This variable indicates whether a UTF-8 locale was detected by perl at -startup. This information is used by perl when it's in -adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line -switch); see L<perlrun> for more info on this. +This variable was added in Perl 5.10. -=item $PERL_VERSION +=item ${^RE_TRIE_MAXBUF} +X<${^RE_TRIE_MAXBUF}> -=item $^V -X<$^V> X<$PERL_VERSION> +Controls how certain regex optimisations are applied and how much memory they +utilize. This value by default is 65536 which corresponds to a 512kB temporary +cache. Set this to a higher value to trade memory for speed when matching +large alternations. Set it to a lower value if you want the optimisations to +be as conservative of memory as possible but still occur, and set it to a +negative value to prevent the optimisation and conserve the most memory. +Under normal situations this variable should be of no interest to you. -The revision, version, and subversion of the Perl interpreter, represented -as a C<version> object. +This variable was added in Perl 5.10. -This variable first appeared in perl 5.6.0; earlier versions of perl will -see an undefined value. Before perl 5.10.0 $^V was represented as a v-string. +=back -$^V can be used to determine whether the Perl interpreter executing a -script is in the right range of versions. (Mnemonic: use ^V for Version -Control.) Example: +=head2 Variables related to filehandles - warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1 +Variables that depend on the currently selected filehandle may be set +by calling an appropriate object method on the C<IO::Handle> object, +although this is less efficient than using the regular built-in +variables. (Summary lines below for this contain the word HANDLE.) +First you must say -To convert C<$^V> into its string representation use sprintf()'s -C<"%vd"> conversion: + use IO::Handle; - printf "version is v%vd\n", $^V; # Perl's version +after which you may use either -See the documentation of C<use VERSION> and C<require VERSION> -for a convenient way to fail if the running Perl interpreter is too old. + method HANDLE EXPR -See also C<$]> for an older representation of the Perl version. +or more safely, -=item $WARNING + HANDLE->method(EXPR) -=item $^W -X<$^W> X<$WARNING> +Each method returns the old value of the C<IO::Handle> attribute. The +methods each take an optional EXPR, which, if supplied, specifies the +new value for the C<IO::Handle> attribute in question. If not +supplied, most methods do nothing to the current value--except for +C<autoflush()>, which will assume a 1 for you, just to be different. -The current value of the warning switch, initially true if B<-w> -was used, false otherwise, but directly modifiable. (Mnemonic: -related to the B<-w> switch.) See also L<warnings>. +Because loading in the C<IO::Handle> class is an expensive operation, +you should learn how to use the regular built-in variables. -=item ${^WARNING_BITS} +A few of these variables are considered "read-only". This means that +if you try to assign to this variable, either directly or indirectly +through a reference, you'll raise a run-time exception. -The current set of warning checks enabled by the C<use warnings> pragma. -See the documentation of C<warnings> for more details. +You should be very careful when modifying the default values of most +special variables described in this document. In most cases you want +to localize these variables before changing them, since if you don't, +the change may affect other modules which rely on the default values +of the special variables that you have changed. This is one of the +correct ways to read the whole file at once: -=item ${^WIN32_SLOPPY_STAT} -X<sitecustomize> X<sitecustomize.pl> + open my $fh, "<", "foo" or die $!; + local $/; # enable localized slurp mode + my $content = <$fh>; + close $fh; -If this variable is set to a true value, then stat() on Windows will -not try to open the file. This means that the link count cannot be -determined and file attributes may be out of date if additional -hardlinks to the file exist. On the other hand, not opening the file -is considerably faster, especially for files on network drives. +But the following code is quite bad: -This variable could be set in the F<sitecustomize.pl> file to -configure the local Perl installation to use "sloppy" stat() by -default. See the documentation for B<-f> in -L<perlrun|perlrun/"Command Switches"> for more information about site -customization. + open my $fh, "<", "foo" or die $!; + undef $/; # enable slurp mode + my $content = <$fh>; + close $fh; -=item $EXECUTABLE_NAME +since some other module, may want to read data from some file in the +default "line mode", so if the code we have just presented has been +executed, the global value of C<$/> is now changed for any other code +running inside the same Perl interpreter. -=item $^X -X<$^X> X<$EXECUTABLE_NAME> +Usually when a variable is localized you want to make sure that this +change affects the shortest scope possible. So unless you are already +inside some short C<{}> block, you should create one yourself. For +example: -The name used to execute the current copy of Perl, from C's -C<argv[0]> or (where supported) F</proc/self/exe>. + my $content = ''; + open my $fh, "<", "foo" or die $!; + { + local $/; + $content = <$fh>; + } + close $fh; -Depending on the host operating system, the value of $^X may be -a relative or absolute pathname of the perl program file, or may -be the string used to invoke perl but not the pathname of the -perl program file. Also, most operating systems permit invoking -programs that are not in the PATH environment variable, so there -is no guarantee that the value of $^X is in PATH. For VMS, the -value may or may not include a version number. +Here is an example of how your own code can go broken: -You usually can use the value of $^X to re-invoke an independent -copy of the same perl that is currently running, e.g., + for ( 1..3 ){ + $\ = "\r\n"; + nasty_break(); + print "$_"; + } - @first_run = `$^X -le "print int rand 100 for 1..100"`; + sub nasty_break { + $\ = "\f"; + # do something with $_ + } -But recall that not all operating systems support forking or -capturing of the output of commands, so this complex statement -may not be portable. +You probably expect this code to print the equivalent of -It is not safe to use the value of $^X as a path name of a file, -as some operating systems that have a mandatory suffix on -executable files do not require use of the suffix when invoking -a command. To convert the value of $^X to a path name, use the -following statements: + "1\r\n2\r\n3\r\n" - # Build up a set of file names (not command names). - use Config; - $this_perl = $^X; - if ($^O ne 'VMS') - {$this_perl .= $Config{_exe} - unless $this_perl =~ m/$Config{_exe}$/i;} +but instead you get: -Because many operating systems permit anyone with read access to -the Perl program file to make a copy of it, patch the copy, and -then execute the copy, the security-conscious Perl programmer -should take care to invoke the installed copy of perl, not the -copy referenced by $^X. The following statements accomplish -this goal, and produce a pathname that can be invoked as a -command or referenced as a file. + "1\f2\f3\f" + +Why? Because C<nasty_break()> modifies C<$\> without localizing it +first. The value you set in C<nasty_break()> is still there when you +return. The fix is to add C<local()> so the value doesn't leak out of +C<nasty_break()>: + + local $\ = "\f"; + +It's easy to notice the problem in such a short example, but in more +complicated code you are looking for trouble if you don't localize +changes to the special variables. + +=over 8 + +=item $ARGV +X<$ARGV> + +Contains the name of the current file when reading from C<< <> >>. + +=item @ARGV +X<@ARGV> - use Config; - $secure_perl_path = $Config{perlpath}; - if ($^O ne 'VMS') - {$secure_perl_path .= $Config{_exe} - unless $secure_perl_path =~ m/$Config{_exe}$/i;} +The array C<@ARGV> contains the command-line arguments intended for +the script. C<$#ARGV> is generally the number of arguments minus +one, because C<$ARGV[0]> is the first argument, I<not> the program's +command name itself. See C<$0> for the command name. =item ARGV X<ARGV> @@ -1448,333 +1523,593 @@ passing C<\*ARGV> as a parameter to a function that expects a filehandle may not cause your function to automatically read the contents of all the files in C<@ARGV>. -=item $ARGV -X<$ARGV> - -contains the name of the current file when reading from <>. - -=item @ARGV -X<@ARGV> - -The array @ARGV contains the command-line arguments intended for -the script. C<$#ARGV> is generally the number of arguments minus -one, because C<$ARGV[0]> is the first argument, I<not> the program's -command name itself. See C<$0> for the command name. - =item ARGVOUT X<ARGVOUT> The special filehandle that points to the currently open output file -when doing edit-in-place processing with B<-i>. Useful when you have -to do a lot of inserting and don't want to keep modifying $_. See +when doing edit-in-place processing with B<-i>. Useful when you have +to do a lot of inserting and don't want to keep modifying C<$_>. See L<perlrun> for the B<-i> switch. -=item @F -X<@F> +=item Handle->output_field_separator( EXPR ) -The array @F contains the fields of each line read in when autosplit -mode is turned on. See L<perlrun> for the B<-a> switch. This array -is package-specific, and must be declared or given a full package name -if not in package main when running under C<strict 'vars'>. +=item $OUTPUT_FIELD_SEPARATOR -=item @INC -X<@INC> +=item $OFS -The array @INC contains the list of places that the C<do EXPR>, -C<require>, or C<use> constructs look for their library files. It -initially consists of the arguments to any B<-I> command-line -switches, followed by the default Perl library, probably -F</usr/local/lib/perl>, followed by ".", to represent the current -directory. ("." will not be appended if taint checks are enabled, either by -C<-T> or by C<-t>.) If you need to modify this at runtime, you should use -the C<use lib> pragma to get the machine-dependent library properly -loaded also: +=item $, +X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR> - use lib '/mypath/libdir/'; - use SomeMod; +The output field separator for the print operator. If defined, this +value is printed between each of print's arguments. Default is C<undef>. -You can also insert hooks into the file inclusion system by putting Perl -code directly into @INC. Those hooks may be subroutine references, array -references or blessed objects. See L<perlfunc/require> for details. +Mnemonic: what is printed when there is a "," in your print statement. -=item @ARG +=item HANDLE->input_line_number( EXPR ) -=item @_ -X<@_> X<@ARG> +=item $INPUT_LINE_NUMBER -Within a subroutine the array @_ contains the parameters passed to that -subroutine. See L<perlsub>. +=item $NR -=item %INC -X<%INC> +=item $. +X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line number> -The hash %INC contains entries for each filename included via the -C<do>, C<require>, or C<use> operators. The key is the filename -you specified (with module names converted to pathnames), and the -value is the location of the file found. The C<require> -operator uses this hash to determine whether a particular file has -already been included. +Current line number for the last filehandle accessed. -If the file was loaded via a hook (e.g. a subroutine reference, see -L<perlfunc/require> for a description of these hooks), this hook is -by default inserted into %INC in place of a filename. Note, however, -that the hook may have set the %INC entry by itself to provide some more -specific info. +Each filehandle in Perl counts the number of lines that have been read +from it. (Depending on the value of C<$/>, Perl's idea of what +constitutes a line may not match yours.) When a line is read from a +filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or +C<seek()> is called on it, C<$.> becomes an alias to the line counter +for that filehandle. -=item %ENV +You can adjust the counter by assigning to C<$.>, but this will not +actually move the seek pointer. I<Localizing C<$.> will not localize +the filehandle's line count>. Instead, it will localize perl's notion +of which filehandle C<$.> is currently aliased to. -=item $ENV{expr} -X<%ENV> +C<$.> is reset when the filehandle is closed, but B<not> when an open +filehandle is reopened without an intervening C<close()>. For more +details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does +an explicit close, line numbers increase across C<ARGV> files (but see +examples in L<perlfunc/eof>). -The hash %ENV contains your current environment. Setting a -value in C<ENV> changes the environment for any child processes -you subsequently fork() off. +You can also use C<< HANDLE->input_line_number(EXPR) >> to access the +line counter for a given filehandle without having to worry about +which handle you last accessed. -=item %SIG +Mnemonic: many programs use "." to mean the current line number. -=item $SIG{expr} -X<%SIG> +=item HANDLE->input_record_separator( EXPR ) -The hash C<%SIG> contains signal handlers for signals. For example: +=item $INPUT_RECORD_SEPARATOR - sub handler { # 1st argument is signal name - my($sig) = @_; - print "Caught a SIG$sig--shutting down\n"; - close(LOG); - exit(0); - } +=item $RS - $SIG{'INT'} = \&handler; - $SIG{'QUIT'} = \&handler; - ... - $SIG{'INT'} = 'DEFAULT'; # restore default action - $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT +=item $/ +X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR> -Using a value of C<'IGNORE'> usually has the effect of ignoring the -signal, except for the C<CHLD> signal. See L<perlipc> for more about -this special case. +The input record separator, newline by default. This influences Perl's +idea of what a "line" is. Works like B<awk>'s RS variable, including +treating empty lines as a terminator if set to the null string (an +empty line cannot contain any spaces or tabs). You may set it to a +multi-character string to match a multi-character terminator, or to +C<undef> to read through the end of file. Setting it to C<"\n\n"> +means something slightly different than setting to C<"">, if the file +contains consecutive empty lines. Setting to C<""> will treat two or +more consecutive empty lines as a single empty line. Setting to +C<"\n\n"> will blindly assume that the next input character belongs to +the next paragraph, even if it's a newline. -Here are some other examples: + local $/; # enable "slurp" mode + local $_ = <FH>; # whole file now here + s/\n[ \t]+/ /g; - $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) - $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber - $SIG{"PIPE"} = *Plumber; # somewhat esoteric - $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? +Remember: the value of C<$/> is a string, not a regex. B<awk> has to +be better for something. :-) -Be sure not to use a bareword as the name of a signal handler, -lest you inadvertently call it. +Setting C<$/> to a reference to an integer, scalar containing an +integer, or scalar that's convertible to an integer will attempt to +read records instead of lines, with the maximum record size being the +referenced integer. So this: -If your system has the sigaction() function then signal handlers are -installed using it. This means you get reliable signal handling. + local $/ = \32768; # or \"32768", or \$var_containing_32768 + open my $fh, "<", $myfile or die $!; + local $_ = <$fh>; -The default delivery policy of signals changed in Perl 5.8.0 from -immediate (also known as "unsafe") to deferred, also known as -"safe signals". See L<perlipc> for more information. +will read a record of no more than 32768 bytes from FILE. If you're +not reading from a record-oriented file (or your OS doesn't have +record-oriented files), then you'll likely get a full chunk of data +with every read. If a record is larger than the record size you've +set, you'll get the record back in pieces. Trying to set the record +size to zero or less will cause reading in the (rest of the) whole file. -Certain internal hooks can be also set using the %SIG hash. The -routine indicated by C<$SIG{__WARN__}> is called when a warning message is -about to be printed. The warning message is passed as the first -argument. The presence of a C<__WARN__> hook causes the ordinary printing -of warnings to C<STDERR> to be suppressed. You can use this to save warnings -in a variable, or turn warnings into fatal errors, like this: +On VMS, record reads are done with the equivalent of C<sysread>, +so it's best not to mix record and non-record reads on the same +file. (This is unlikely to be a problem, because any file you'd +want to read in record mode is probably unusable in line mode.) +Non-VMS systems do normal I/O, so it's safe to mix record and +non-record reads of a file. - local $SIG{__WARN__} = sub { die $_[0] }; - eval $proggie; +See also L<perlport/"Newlines">. Also see C<$.>. -As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can -disable warnings using the empty subroutine: +Mnemonic: / delimits line boundaries when quoting poetry. - local $SIG{__WARN__} = sub {}; +=item Handle->output_record_separator( EXPR ) -The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception -is about to be thrown. The error message is passed as the first -argument. When a C<__DIE__> hook routine returns, the exception -processing continues as it would have in the absence of the hook, -unless the hook routine itself exits via a C<goto>, a loop exit, or a C<die()>. -The C<__DIE__> handler is explicitly disabled during the call, so that you -can die from a C<__DIE__> handler. Similarly for C<__WARN__>. +=item $OUTPUT_RECORD_SEPARATOR -Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called -even inside an eval(). Do not use this to rewrite a pending exception -in C<$@>, or as a bizarre substitute for overriding C<CORE::GLOBAL::die()>. -This strange action at a distance may be fixed in a future release -so that C<$SIG{__DIE__}> is only called if your program is about -to exit, as was the original intent. Any other use is deprecated. - -C<__DIE__>/C<__WARN__> handlers are very special in one respect: -they may be called to report (probable) errors found by the parser. -In such a case the parser may be in inconsistent state, so any -attempt to evaluate Perl code from such a handler will probably -result in a segfault. This means that warnings or errors that -result from parsing Perl should be used with extreme caution, like -this: - - require Carp if defined $^S; - Carp::confess("Something wrong") if defined &Carp::confess; - die "Something wrong, but could not load Carp to give backtrace... - To see backtrace try starting Perl with -MCarp switch"; - -Here the first line will load Carp I<unless> it is the parser who -called the handler. The second line will print backtrace and die if -Carp was available. The third line will be executed only if Carp was -not available. +=item $ORS -See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and -L<warnings> for additional information. +=item $\ +X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR> + +The output record separator for the print operator. If defined, this +value is printed after the last of print's arguments. Default is C<undef>. + +Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. +Also, it's just like C<$/>, but it's what you get "back" from Perl. + +=item HANDLE->autoflush( EXPR ) + +=item $OUTPUT_AUTOFLUSH + +=item $| +X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH> + +If set to nonzero, forces a flush right away and after every write or +print on the currently selected output channel. Default is 0 +(regardless of whether the channel is really buffered by the system or +not; C<$|> tells you only whether you've asked Perl explicitly to +flush after each write). STDOUT will typically be line buffered if +output is to the terminal and block buffered otherwise. Setting this +variable is useful primarily when you are outputting to a pipe or +socket, such as when you are running a Perl program under B<rsh> and +want to see the output as it's happening. This has no effect on input +buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on +how to select the output channel. See also L<IO::Handle>. + +Mnemonic: when you want your pipes to be piping hot. =back -=head2 Names that are no longer special +=head3 Variables related to formats -These variables had special meaning in prior versions of Perl but now -have no effect and will cause warnings if used. They are included -here for historical reference. +The special variables for formats are a subset of those for +filehandles. See L<perlform> for more information about Perl's +formats. =over 8 -=item $# -X<$#> +=item $ACCUMULATOR -C<$#> used to be a variable that could be used to format printed numbers. -After a deprecation cycle, its magic was removed in Perl 5.10 and using it -now triggers a warning: C<$# is no longer supported>. +=item $^A +X<$^A> X<$ACCUMULATOR> -C<$#> is also used as sigil, which, when prepended on the name of an -array, gives the index of the last element in that array. +The current value of the C<write()> accumulator for C<format()> lines. +A format contains C<formline()> calls that put their result into +C<$^A>. After calling its format, C<write()> prints out the contents +of C<$^A> and empties. So you never really see the contents of C<$^A> +unless you call C<formline()> yourself and then look at it. See +L<perlform> and L<perlfunc/"formline PICTURE,LIST">. - my @array = ("a", "b", "c"); - my $last_index = $#array; # $last_index is 2 +=item HANDLE->format_formfeed(EXPR) - for my $i (0 .. $#array) { - print "The value of index $i is $array[$i]\n"; - } +=item $FORMAT_FORMFEED -Also see L<perldata>. +=item $^L +X<$^L> X<$FORMAT_FORMFEED> -=item $* -X<$*> +What formats output as a form feed. The default is C<\f>. -C<$*> used to be a variable that enabled multiline matching. -After a deprecation cycle, its magic was removed in Perl 5.10. -Using it now triggers a warning: C<$* is no longer supported>. -Use the C</s> and C</m> regexp modifiers instead. +=item HANDLE->format_page_number(EXPR) + +=item $FORMAT_PAGE_NUMBER + +=item $% +X<$%> X<$FORMAT_PAGE_NUMBER> + +The current page number of the currently selected output channel. + +Mnemonic: C<%> is page number in B<nroff>. + +=item HANDLE->format_lines_left(EXPR) + +=item $FORMAT_LINES_LEFT + +=item $- +X<$-> X<$FORMAT_LINES_LEFT> + +The number of lines left on the page of the currently selected output +channel. + +Mnemonic: lines_on_page - lines_printed. + +=item Handle->format_line_break_characters EXPR + +=item $FORMAT_LINE_BREAK_CHARACTERS + +=item $: +X<$:> X<FORMAT_LINE_BREAK_CHARACTERS> + +The current set of characters after which a string may be broken to +fill continuation fields (starting with C<^>) in a format. The default is +S<" \n-">, to break on a space, newline, or a hyphen. + +Mnemonic: a "colon" in poetry is a part of a line. + +=item HANDLE->format_lines_per_page(EXPR) + +=item $FORMAT_LINES_PER_PAGE + +=item $= +X<$=> X<$FORMAT_LINES_PER_PAGE> + +The current page length (printable lines) of the currently selected +output channel. The default is 60. + +Mnemonic: = has horizontal lines. + +=item HANDLE->format_top_name(EXPR) + +=item $FORMAT_TOP_NAME + +=item $^ +X<$^> X<$FORMAT_TOP_NAME> + +The name of the current top-of-page format for the currently selected +output channel. The default is the name of the filehandle with C<_TOP> +appended. For example, the default format top name for the C<STDOUT> +filehanlde is C<STDOUT_TOP>. + +Mnemonic: points to top of page. + +=item HANDLE->format_name(EXPR) + +=item $FORMAT_NAME + +=item $~ +X<$~> X<$FORMAT_NAME> + +The name of the current report format for the currently selected +output channel. The default format name is the same as the filehandle +name. For example, the default format name for the C<STDOUT> +filehandle is just C<STDOUT>. -Also see L<perlre>. +Mnemonic: brother to C<$^>. =back -=head2 Error Indicators +=head2 Error Variables X<error> X<exception> The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information about different types of error conditions that may appear during -execution of a Perl program. The variables are shown ordered by +execution of a Perl program. The variables are shown ordered by the "distance" between the subsystem which reported the error and -the Perl process. They correspond to errors detected by the Perl +the Perl process. They correspond to errors detected by the Perl interpreter, C library, operating system, or an external program, respectively. To illustrate the differences between these variables, consider the -following Perl expression, which uses a single-quoted string: +following Perl expression, which uses a single-quoted string. After +execution of this statement, perl may have set all four special error +variables: + + eval q{ + open my $pipe, "/cdrom/install |" or die $!; + my @res = <$pipe>; + close $pipe or die "bad pipe: $?, $!"; + }; + +When perl executes the C<eval()> expression, it translates the +C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library +and thence to the operating system kernel. perl sets C<$!> to +the C library's C<errno> if one of these calls fails. + +C<$@> is set if the string to be C<eval>-ed did not compile (this may +happen if C<open> or C<close> were imported with bad prototypes), or +if Perl code executed during evaluation C<die()>d. In these cases the +value of C<$@> is the compile error, or the argument to C<die> (which +will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.) + +Under a few operating systems, C<$^E> may contain a more verbose error +indicator, such as in this case, "CDROM tray not closed." Systems that +do not support extended error messages leave C<$^E> the same as C<$!>. - eval q{ - open my $pipe, "/cdrom/install |" or die $!; - my @res = <$pipe>; - close $pipe or die "bad pipe: $?, $!"; - }; +Finally, C<$?> may be set to non-0 value if the external program +F</cdrom/install> fails. The upper eight bits reflect specific error +conditions encountered by the program (the program's C<exit()> value). +The lower eight bits reflect mode of failure, like signal death and +core dump information. See C<wait(2)> for details. In contrast to +C<$!> and C<$^E>, which are set only if error condition is detected, +the variable C<$?> is set on each C<wait> or pipe C<close>, +overwriting the old value. This is more like C<$@>, which on every +C<eval()> is always set on failure and cleared on success. + +For more details, see the individual descriptions at C<$@>, C<$!>, +C<$^E>, and C<$?>. -After execution of this statement all 4 variables may have been set. +=over 8 -C<$@> is set if the string to be C<eval>-ed did not compile (this -may happen if C<open> or C<close> were imported with bad prototypes), -or if Perl code executed during evaluation die()d . In these cases -the value of $@ is the compile error, or the argument to C<die> -(which will interpolate C<$!> and C<$?>). (See also L<Fatal>, -though.) +=item ${^CHILD_ERROR_NATIVE} +X<$^CHILD_ERROR_NATIVE> -When the eval() expression above is executed, open(), C<< <PIPE> >>, -and C<close> are translated to calls in the C run-time library and -thence to the operating system kernel. C<$!> is set to the C library's -C<errno> if one of these calls fails. +The native status returned by the last pipe close, backtick (C<``>) +command, successful call to C<wait()> or C<waitpid()>, or from the +C<system()> operator. On POSIX-like systems this value can be decoded +with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, +WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module. -Under a few operating systems, C<$^E> may contain a more verbose -error indicator, such as in this case, "CDROM tray not closed." -Systems that do not support extended error messages leave C<$^E> -the same as C<$!>. +Under VMS this reflects the actual VMS exit status; i.e. it is the +same as C<$?> when the pragma C<use vmsish 'status'> is in effect. -Finally, C<$?> may be set to non-0 value if the external program -F</cdrom/install> fails. The upper eight bits reflect specific -error conditions encountered by the program (the program's exit() -value). The lower eight bits reflect mode of failure, like signal -death and core dump information See wait(2) for details. In -contrast to C<$!> and C<$^E>, which are set only if error condition -is detected, the variable C<$?> is set on each C<wait> or pipe -C<close>, overwriting the old value. This is more like C<$@>, which -on every eval() is always set on failure and cleared on success. +This variable was added in Perl 5.8.9. -For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>, -and C<$?>. +=item $EXTENDED_OS_ERROR -=head2 Technical Note on the Syntax of Variable Names +=item $^E +X<$^E> X<$EXTENDED_OS_ERROR> -Variable names in Perl can have several formats. Usually, they -must begin with a letter or underscore, in which case they can be -arbitrarily long (up to an internal limit of 251 characters) and -may contain letters, digits, underscores, or the special sequence -C<::> or C<'>. In this case, the part before the last C<::> or -C<'> is taken to be a I<package qualifier>; see L<perlmod>. +Error information specific to the current operating system. At the +moment, this differs from C<$!> under only VMS, OS/2, and Win32 (and +for MacPerl). On all other platforms, C<$^E> is always just the same +as C<$!>. -Perl variable names may also be a sequence of digits or a single -punctuation or control character. These names are all reserved for -special uses by Perl; for example, the all-digits names are used -to hold data captured by backreferences after a regular expression -match. Perl has a special syntax for the single-control-character -names: It understands C<^X> (caret C<X>) to mean the control-C<X> -character. For example, the notation C<$^W> (dollar-sign caret -C<W>) is the scalar variable whose name is the single character -control-C<W>. This is better than typing a literal control-C<W> -into your program. +Under VMS, C<$^E> provides the VMS status value from the last system +error. This is more specific information about the last system error +than that provided by C<$!>. This is particularly important when C<$!> +is set to B<EVMSERR>. -Finally, new in Perl 5.6, Perl variable names may be alphanumeric -strings that begin with control characters (or better yet, a caret). -These variables must be written in the form C<${^Foo}>; the braces -are not optional. C<${^Foo}> denotes the scalar variable whose -name is a control-C<F> followed by two C<o>'s. These variables are -reserved for future special uses by Perl, except for the ones that -begin with C<^_> (control-underscore or caret-underscore). No -control-character name that begins with C<^_> will acquire a special -meaning in any future version of Perl; such names may therefore be -used safely in programs. C<$^_> itself, however, I<is> reserved. +Under OS/2, C<$^E> is set to the error code of the last call to OS/2 +API either via CRT, or directly from perl. -Perl identifiers that begin with digits, control characters, or -punctuation characters are exempt from the effects of the C<package> -declaration and are always forced to be in package C<main>; they are -also exempt from C<strict 'vars'> errors. A few other names are also -exempt in these ways: +Under Win32, C<$^E> always returns the last error information reported +by the Win32 call C<GetLastError()> which describes the last error +from within the Win32 API. Most Win32-specific code will report errors +via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most +portable Perl code will report errors via C<$!>. - ENV STDIN - INC STDOUT - ARGV STDERR - ARGVOUT _ - SIG +Caveats mentioned in the description of C<$!> generally apply to +C<$^E>, also. -In particular, the new special C<${^_XYZ}> variables are always taken -to be in package C<main>, regardless of any C<package> declarations -presently in scope. +This variable was added in Perl 5.003. -=head1 BUGS +Mnemonic: Extra error explanation. -Due to an unfortunate accident of Perl's implementation, C<use -English> imposes a considerable performance penalty on all regular -expression matches in a program, regardless of whether they occur -in the scope of C<use English>. For that reason, saying C<use -English> in libraries is strongly discouraged. See the -Devel::SawAmpersand module documentation from CPAN -( http://www.cpan.org/modules/by-module/Devel/ ) -for more information. Writing C<use English '-no_match_vars';> -avoids the performance penalty. +=item $EXCEPTIONS_BEING_CAUGHT -Having to even think about the C<$^S> variable in your exception -handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented -invites grievous and difficult to track down errors. Avoid it -and use an C<END{}> or CORE::GLOBAL::die override instead. +=item $^S +X<$^S> X<$EXCEPTIONS_BEING_CAUGHT> + +Current state of the interpreter. + + $^S State + --------- ------------------- + undef Parsing module/eval + true (1) Executing an eval + false (0) Otherwise + +The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}> +handlers. + +This variable was added in Perl 5.004. + +=item $WARNING + +=item $^W +X<$^W> X<$WARNING> + +The current value of the warning switch, initially true if B<-w> was +used, false otherwise, but directly modifiable. + +See also L<warnings>. + +Mnemonic: related to the B<-w> switch. + +=item ${^WARNING_BITS} +X<${^WARNING_BITS}> + +The current set of warning checks enabled by the C<use warnings> pragma. +See the documentation of C<warnings> for more details. + +This variable was added in Perl 5.10. + +=item $OS_ERROR + +=item $ERRNO + +=item $! +X<$!> X<$ERRNO> X<$OS_ERROR> + +If used numerically, yields the current value of the C C<errno> +variable, or in other words, if a system or library call fails, it +sets this variable. This means that the value of C<$!> is meaningful +only I<immediately> after a B<failure>: + + if (open my $fh, "<", $filename) { + # Here $! is meaningless. + ... + } + else { + # ONLY here is $! meaningful. + ... + # Already here $! might be meaningless. + } + # Since here we might have either success or failure, + # here $! is meaningless. + +The I<meaningless> stands for anything: zero, non-zero, +C<undef>. A successful system or library call does B<not> set the +variable to zero. + +If used as a string, yields the corresponding system error string. You +can assign a number to C<$!> to set I<errno> if, for instance, you +want C<"$!"> to return the string for error I<n>, or you want to set +the exit value for the C<die()> operator. + +Mnemonic: What just went bang? + +=item %OS_ERROR + +=item %ERRNO + +=item %! +X<%!> X<%OS_ERROR> X<%ERRNO> + +Each element of C<%!> has a true value only if C<$!> is set to that +value. For example, C<$!{ENOENT}> is true if and only if the current +value of C<$!> is C<ENOENT>; that is, if the most recent error was "No +such file or directory" (or its moral equivalent: not all operating +systems give that exact error, and certainly not all languages). To +check if a particular key is meaningful on your system, use C<exists +$!{the_key}>; for a list of legal keys, use C<keys %!>. See L<Errno> +for more information, and also see L</$!>. + +This variable was added in Perl 5.005. + +=item $CHILD_ERROR + +=item $? +X<$?> X<$CHILD_ERROR> + +The status returned by the last pipe close, backtick (C<``>) command, +successful call to C<wait()> or C<waitpid()>, or from the C<system()> +operator. This is just the 16-bit status word returned by the +traditional Unix C<wait()> system call (or else is made up to look +like it). Thus, the exit value of the subprocess is really (C<<< $? >> +8 >>>), and C<$? & 127> gives which signal, if any, the process died +from, and C<$? & 128> reports whether there was a core dump. + +Additionally, if the C<h_errno> variable is supported in C, its value +is returned via C<$?> if any C<gethost*()> function fails. + +If you have installed a signal handler for C<SIGCHLD>, the +value of C<$?> will usually be wrong outside that handler. + +Inside an C<END> subroutine C<$?> contains the value that is going to be +given to C<exit()>. You can modify C<$?> in an C<END> subroutine to +change the exit status of your program. For example: + + END { + $? = 1 if $? == 255; # die would make it 255 + } + +Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the +actual VMS exit status, instead of the default emulation of POSIX +status; see L<perlvms/$?> for details. + +Mnemonic: similar to B<sh> and B<ksh>. + +=item $EVAL_ERROR + +=item $@ +X<$@> X<$EVAL_ERROR> + +The Perl syntax error message from the last C<eval()> operator. If C<$@> is +the null string, the last C<eval()> parsed and executed correctly +(although the operations you invoked may have failed in the normal +fashion). + +Warning messages are not collected in this variable. You can, however, +set up a routine to process warnings by setting C<$SIG{__WARN__}> as +described in L</%SIG>. + +Mnemonic: Where was the syntax error "at"? + +=back + +=head2 Deprecated and removed variables + +Deprecating a variable announces the intent of the perl maintainers to +eventually remove the variable from the langauge. It may still be +available despite its status. Using a deprecated variable triggers +a warning. + +Once a variable is removed, its use triggers an error telling you +the variable is unsupported. + +See L<perldiag> for details about error messages. + +=over 8 + +=item $OFMT + +=item $# +X<$#> X<$OFMT> + +C<$#> was a variable that you could be use to format printed numbers. +After a deprecation cycle, its magic was removed in Perl 5.10 and +using it now triggers a warning: C<$# is no longer supported>. + +This is not the sigil you use in front of an array name to get the +last index, like C<$#array>. That's still how you get the last index +of an array in Perl. The two have nothing to do with each other. + +Deprecated in Perl 5. + +Removed in Perl 5.10. + +=item $* +X<$*> + +C<$*> was a variable that you could use to enable multiline matching. +After a deprecation cycle, its magic was removed in Perl 5.10. +Using it now triggers a warning: C<$* is no longer supported>. +You should use the C</s> and C</m> regexp modifiers instead. + +Deprecated in Perl 5. + +Removed in Perl 5.10. + +=item $ARRAY_BASE + +=item $[ +X<$[> X<$ARRAY_BASE> + +This variable stores the index of the first element in an array, and +of the first character in a substring. The default is 0, but you could +theoretically set it to 1 to make Perl behave more like B<awk> (or Fortran) +when subscripting and when evaluating the index() and substr() functions. + +As of release 5 of Perl, assignment to C<$[> is treated as a compiler +directive, and cannot influence the behavior of any other file. +(That's why you can only assign compile-time constants to it.) +Its use is highly discouraged. + +Prior to Perl 5.10, assignment to C<$[> could be seen from outer lexical +scopes in the same file, unlike other compile-time directives (such as +L<strict>). Using local() on it would bind its value strictly to a lexical +block. Now it is always lexically scoped. + +Mnemonic: [ begins subscripts. + +Deprecated in Perl 5.12. + +=item $OLD_PERL_VERSION + +=item $] +X<$]> X<$OLD_PERL_VERSION> + +See C<$^V> for a more modern representation of the Perl version that allows +accurate string comparisons. + +The version + patchlevel / 1000 of the Perl interpreter. This variable +can be used to determine whether the Perl interpreter executing a +script is in the right range of versions: + + warn "No checksumming!\n" if $] < 3.019; + +The floating point representation can sometimes lead to inaccurate +numeric comparisons. + +See also the documentation of C<use VERSION> and C<require VERSION> +for a convenient way to fail if the running Perl interpreter is too old. + +Mnemonic: Is this version of perl in the right bracket? + +Deprecated in Perl 5.6. + +=back + +=cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlvmesa.pod b/Master/tlpkg/tlperl/lib/pods/perlvmesa.pod index 98fa5ec9cfd..27c3aec7096 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlvmesa.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlvmesa.pod @@ -37,7 +37,7 @@ To extract an ASCII tar archive on VM/ESA, try this: GNU make for VM/ESA, which may be required for the build of perl, is available from: - http://vm.marist.edu/~neale/vmoe.html +L<http://vm.marist.edu/~neale/vmoe.html> =head2 Configure Perl on VM/ESA @@ -120,12 +120,21 @@ To subscribe, send an empty message to perl-mvs-subscribe@perl.org. See also: - http://lists.perl.org/showlist.cgi?name=perl-mvs +L<http://lists.perl.org/showlist.cgi?name=perl-mvs> There are web archives of the mailing list at: - http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/ - http://archive.develooper.com/perl-mvs@perl.org/ +=over 4 + +=item * + +L<http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/> + +=item * + +L<http://archive.develooper.com/perl-mvs@perl.org/> + +=back =cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlvms.pod b/Master/tlpkg/tlperl/lib/pods/perlvms.pod index 17175db3bd9..7e96c06b054 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlvms.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlvms.pod @@ -265,14 +265,14 @@ created by an older version of an archive utility or a build utility such as MMK or MMS may generate a filename in all upper case even on an ODS-5 volume. If this filename is later retrieved by a Perl script or module in a case preserving environment, that upper case name may not -match the mixed-case or lower-case expections of the Perl code. Your +match the mixed-case or lower-case exceptions of the Perl code. Your best bet is to follow an all-or-nothing approach to case preservation: either don't use it at all, or make sure your entire toolchain and application environment support and use it. OpenVMS Alpha v7.3-1 and later and all version of OpenVMS I64 support case sensitivity as a process setting (see C<SET PROCESS -/CASE_LOOKUP=SENSITIVE>). Perl does not currently suppport case +/CASE_LOOKUP=SENSITIVE>). Perl does not currently support case sensitivity on VMS, but it may in the future, so Perl programs should use the C<< File::Spec->case_tolerant >> method to determine the state, and not the C<$^O> variable. @@ -848,10 +848,10 @@ Therefore, the "system time" elements will always be 0, since there is no difference between "user time" and "system" time under VMS, and the time accumulated by a subprocess may or may not appear separately in the "child time" field, depending on -whether L<times> keeps track of subprocesses separately. Note +whether C<times()> keeps track of subprocesses separately. Note especially that the VAXCRTL (at least) keeps track only of -subprocesses spawned using L<fork> and L<exec>; it will not -accumulate the times of subprocesses spawned via pipes, L<system>, +subprocesses spawned using C<fork()> and C<exec()>; it will not +accumulate the times of subprocesses spawned via pipes, C<system()>, or backticks. =item unlink LIST @@ -1188,7 +1188,7 @@ consequence of ignoring this advice will be undefined to allow future improvements in the POSIX exit handling. In general, with C<PERL_VMS_POSIX_EXIT> enabled, more detailed information -will be availble in the exit status for DCL scripts or other native VMS tools, +will be available in the exit status for DCL scripts or other native VMS tools, and will give the expected information for Posix programs. It has not been made the default in order to preserve backward compatibility. diff --git a/Master/tlpkg/tlperl/lib/pods/perlwin32.pod b/Master/tlpkg/tlperl/lib/pods/perlwin32.pod index f9c3353b6d7..67869cac6cc 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlwin32.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlwin32.pod @@ -8,8 +8,7 @@ perlwin32 - Perl under Windows =head1 SYNOPSIS -These are instructions for building Perl under Windows 9x/NT/2000/XP -on the Intel x86 and Itanium architectures. +These are instructions for building Perl under Windows 2000 and later. =head1 DESCRIPTION @@ -26,56 +25,62 @@ only relevant to people building Perl on Unix-like systems. In particular, you can safely ignore any information that talks about "Configure". -You may also want to look at two other options for building -a perl that will work on Windows NT: the README.cygwin and -README.os2 files, each of which give a different set of rules to -build a Perl that will work on Win32 platforms. Those two methods -will probably enable you to build a more Unix-compatible perl, but -you will also need to download and use various other build-time and -run-time support software described in those files. +You may also want to look at one other option for building a perl that +will work on Windows: the README.cygwin file, which give a different +set of rules to build a perl for Windows. This method will probably +enable you to build a more Unix-compatible perl, but you will also +need to download and use various other build-time and run-time support +software described in that file. This set of instructions is meant to describe a so-called "native" -port of Perl to Win32 platforms. This includes both 32-bit and +port of Perl to the Windows platform. This includes both 32-bit and 64-bit Windows operating systems. The resulting Perl requires no additional software to run (other than what came with your operating system). Currently, this port is capable of using one of the following compilers on the Intel x86 architecture: - Borland C++ version 5.02 or later - Microsoft Visual C++ version 2.0 or later - MinGW with gcc gcc version 2.95.2 or later - Gcc by mingw.org gcc version 2.95.2 or later + Borland C++ version 5.02 or later + Microsoft Visual C++ version 6.0 or later + Gcc by mingw.org gcc version 3.2 or later Gcc by mingw-w64.sf.net gcc version 4.4.3 or later Note that the last two of these are actually competing projects both delivering complete gcc toolchain for MS Windows: -- http://mingw.org - delivers gcc toolchain targeting 32-bit Windows - platform. - Use version 3.2.x or later for the best results with this compiler. -- http://mingw-w64.sf.net - delivers gcc toolchain targeting both 64-bit - Windows and 32-bit Windows platforms (despite the project name "mingw-w64" - they are not only 64-bit oriented). They deliver the native gcc compilers - + cross-compilers that are also supported by perl's makefile. + +=over 4 + +=item L<http://mingw.org> + +Delivers gcc toolchain targeting 32-bit Windows platform. + +=item L<http://mingw-w64.sf.net> + +Delivers gcc toolchain targeting both 64-bit Windows and 32-bit Windows +platforms (despite the project name "mingw-w64" they are not only 64-bit +oriented). They deliver the native gcc compilers and cross-compilers +that are also supported by perl's makefile. + +=back The Borland C++ and Microsoft Visual C++ compilers are also now being given away free. The Borland compiler is available as "Borland C++ Compiler Free Command Line Tools" and is the same compiler that ships with the full "Borland C++ Builder" product. The Microsoft compiler is available as -"Visual C++ Toolkit 2003" or "Visual C++ 2005/2008 Express Edition" (and also -as part of the ".NET Framework SDK") and is the same compiler that ships with -"Visual C++ .NET 2003 Professional" or "Visual C++ 2005/2008 Professional" -respectively. +"Visual C++ Toolkit 2003" or "Visual C++ 2005/2008/2010 Express Edition" (and +also as part of the ".NET Framework SDK") and is the same compiler that ships +with "Visual C++ .NET 2003 Professional" or "Visual C++ 2005/2008/2010 +Professional" respectively. This port can also be built on IA64/AMD64 using: Microsoft Platform SDK Nov 2001 (64-bit compiler and tools) MinGW64 compiler (gcc version 4.4.3 or later) -The MS Platform SDK can be downloaded from http://www.microsoft.com/. -The MinGW64 compiler is available at http://sourceforge.net/projects/mingw-w64. +The Windows SDK can be downloaded from L<http://www.microsoft.com/>. +The MinGW64 compiler is available at L<http://sourceforge.net/projects/mingw-w64>. The latter is actually a cross-compiler targeting Win64. There's also a trimmed down compiler (no java, or gfortran) suitable for building perl available at: -http://strawberryperl.com/package/kmx/64_gcctoolchain/mingw64-w64-20100123-kmx-v2.zip +L<http://strawberryperl.com/package/kmx/64_gcctoolchain/mingw64-w64-20100123-kmx-v2.zip> NOTE: If you're using a 32-bit compiler to build perl on a 64-bit Windows operating system, then you should set the WIN64 environment variable to "undef". @@ -85,24 +90,24 @@ Also, the trimmed down compiler only passes tests when USE_ITHREADS *= define This port fully supports MakeMaker (the set of modules that is used to build extensions to perl). Therefore, you should be able to build and install most extensions found in the CPAN sites. -See L<Usage Hints for Perl on Win32> below for general hints about this. +See L<Usage Hints for Perl on Windows> below for general hints about this. -=head2 Setting Up Perl on Win32 +=head2 Setting Up Perl on Windows =over 4 =item Make You need a "make" program to build the sources. If you are using -Visual C++ or the Platform SDK tools under Windows NT/2000/XP, nmake -will work. All other builds need dmake. +Visual C++ or the Windows SDK tools, nmake will work. Builds using +the Borland compiler or gcc need dmake. dmake is a freely available make that has very nice macro features and parallelability. A port of dmake for Windows is available from: - http://search.cpan.org/dist/dmake/ +L<http://search.cpan.org/dist/dmake/> Fetch and install dmake somewhere on your path. @@ -118,17 +123,11 @@ available in the win32 subdirectory of the Perl source distribution. =item Command Shell -Use the default "cmd" shell that comes with NT. Some versions of the +Use the default "cmd" shell that comes with Windows. Some versions of the popular 4DOS/NT shell have incompatibilities that may cause you trouble. If the build fails under that shell, try building again with the cmd shell. -The nmake Makefile also has known incompatibilities with the -"command.com" shell that comes with Windows 9x. You will need to -use dmake and makefile.mk to build under Windows 9x. - -The surest way to build it is on Windows NT/2000/XP, using the cmd shell. - Make sure the path to the build directory does not contain spaces. The build usually works in this circumstance, but some tests will fail. @@ -144,7 +143,7 @@ See L</"Make"> above. The nmake that comes with Visual C++ will suffice for building. You will need to run the VCVARS32.BAT file, usually found somewhere -like C:\MSDEV4.2\BIN or C:\Program Files\Microsoft Visual Studio\VC98\Bin. +like C:\Program Files\Microsoft Visual Studio\VC98\Bin. This will set your build environment. You can also use dmake to build using Visual C++; provided, however, @@ -154,31 +153,26 @@ and edit win32/config.vc to change "make=nmake" into "make=dmake". The latter step is only essential if you want to use dmake as your default make for building extensions using MakeMaker. -=item Microsoft Visual C++ 2008 Express Edition +=item Microsoft Visual C++ 2008/2010 Express Edition -This free version of Visual C++ 2008 Professional contains the same compiler -and linker that ship with the full version, and also contains everything -necessary to build Perl, rather than requiring a separate download of the -Platform SDK like previous versions did. +These free versions of Visual C++ 2008/2010 Professional contain the same +compilers and linkers that ship with the full versions, and also contain +everything necessary to build Perl, rather than requiring a separate download +of the Windows SDK like previous versions did. -This package can be downloaded by searching for "Visual Studio 2008 Express -Edition" in the Download Center at -http://www.microsoft.com/downloads/search.aspx?displaylang=en. (Providing exact +These packages can be downloaded by searching in the Download Center at +L<http://www.microsoft.com/downloads/search.aspx?displaylang=en>. (Providing exact links to these packages has proven a pointless task because the links keep on changing so often.) -Install Visual C++ 2008, then setup your environment using +Install Visual C++ 2008/2010 Express, then setup your environment using, e.g. - C:\Program Files\Microsoft Visual Studio 9.0\Common7\Tools\vsvars32.bat + C:\Program Files\Microsoft Visual Studio 10.0\Common7\Tools\vsvars32.bat (assuming the default installation location was chosen). Perl should now build using the win32/Makefile. You will need to edit that -file to set - - CCTYPE = MSVC90FREE - -first. +file to set CCTYPE to MSVC90FREE or MSVC100FREE first. =item Microsoft Visual C++ 2005 Express Edition @@ -186,23 +180,19 @@ This free version of Visual C++ 2005 Professional contains the same compiler and linker that ship with the full version, but doesn't contain everything necessary to build Perl. -You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC +You will also need to download the "Windows SDK" (the "Core SDK" and "MDAC SDK" components are required) for more header files and libraries. These packages can both be downloaded by searching in the Download Center at -http://www.microsoft.com/downloads/search.aspx?displaylang=en. (Providing exact +L<http://www.microsoft.com/downloads/search.aspx?displaylang=en>. (Providing exact links to these packages has proven a pointless task because the links keep on changing so often.) -Try to obtain the latest version of the Platform SDK. Sometimes these packages +Try to obtain the latest version of the Windows SDK. Sometimes these packages contain a particular Windows OS version in their name, but actually work on other OS versions too. For example, the "Windows Server 2003 R2 Platform SDK" also runs on Windows XP SP2 and Windows 2000. -According to the download pages these packages are only supported on Windows -2000/XP/2003, so trying to use these tools on Windows 95/98/ME and even Windows -NT probably won't work. - Install Visual C++ 2005 first, then the Platform SDK. Setup your environment as follows (assuming default installation locations were chosen): @@ -242,19 +232,15 @@ Framework Redistributable" to be installed first. This can be downloaded and installed separately, but is included in the "Visual C++ Toolkit 2003" anyway. These packages can all be downloaded by searching in the Download Center at -http://www.microsoft.com/downloads/search.aspx?displaylang=en. (Providing exact +L<http://www.microsoft.com/downloads/search.aspx?displaylang=en>. (Providing exact links to these packages has proven a pointless task because the links keep on changing so often.) -Try to obtain the latest version of the Platform SDK. Sometimes these packages +Try to obtain the latest version of the Windows SDK. Sometimes these packages contain a particular Windows OS version in their name, but actually work on other OS versions too. For example, the "Windows Server 2003 R2 Platform SDK" also runs on Windows XP SP2 and Windows 2000. -According to the download pages these packages are only supported on Windows -2000/XP/2003, so trying to use these tools on Windows 95/98/ME and even Windows -NT probably won't work. - Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK. Setup your environment as follows (assuming default installation locations were chosen): @@ -341,55 +327,13 @@ shells available after you install the Platform SDK from the Start Menu. =item MinGW release 3 with gcc -The latest release of MinGW at the time of writing is 3.1.0, which contains -gcc-3.2.3. It can be downloaded here: - - http://www.mingw.org/ +Perl can be compiled with gcc from MinGW release 3 and later (using gcc 3.2.x +and later). It can be downloaded here: -Perl also compiles with earlier releases of gcc (2.95.2 and up). See below -for notes about using earlier versions of MinGW/gcc. - -And perl also compiles with gcc-4.3.0 and up, and perhaps even some of the -earlier 4.x.x versions. +L<http://www.mingw.org/> You also need dmake. See L</"Make"> above on how to get it. -=item MinGW release 1 with gcc - -The MinGW-1.1 bundle contains gcc-2.95.3. - -Make sure you install the binaries that work with MSVCRT.DLL as indicated -in the README for the GCC bundle. You may need to set up a few environment -variables (usually ran from a batch file). - -There are a couple of problems with the version of gcc-2.95.2-msvcrt.exe -released 7 November 1999: - -=over - -=item * - -It left out a fix for certain command line quotes. To fix this, be sure -to download and install the file fixes/quote-fix-msvcrt.exe from the above -ftp location. - -=item * - -The definition of the fpos_t type in stdio.h may be wrong. If your -stdio.h has this problem, you will see an exception when running the -test t/lib/io_xs.t. To fix this, change the typedef for fpos_t from -"long" to "long long" in the file i386-mingw32msvc/include/stdio.h, -and rebuild. - -=back - -A potentially simpler to install (but probably soon-to-be-outdated) bundle -of the above package with the mentioned fixes already applied is available -here: - - http://downloads.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip - ftp://ftp.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip - =back =head2 Building @@ -400,7 +344,7 @@ here: Make sure you are in the "win32" subdirectory under the perl toplevel. This directory contains a "Makefile" that will work with -versions of nmake that come with Visual C++ or the Platform SDK, and +versions of nmake that come with Visual C++ or the Windows SDK, and a dmake "makefile.mk" that will work for all supported compilers. The defaults in the dmake makefile are setup to build using MinGW/gcc. @@ -437,19 +381,6 @@ You may also need to comment out the C<DELAYLOAD = ...> line in the Makefile if you're using VC++ 6.0 without the latest service pack and the linker reports an internal error. -If you are using VC++ 4.2 or earlier then you'll have to change the /EHsc -option in the CXX_FLAG macro to the equivalent /GX option. - -If you have either the source or a library that contains des_fcrypt(), -enable the appropriate option in the makefile. A ready-to-use version -of fcrypt.c, based on the version originally written by Eric Young at -ftp://ftp.funet.fi/pub/crypt/mirrors/dsi/libdes/, is bundled with the -distribution and CRYPT_SRC is set to use it. -Alternatively, if you have built a library that contains des_fcrypt(), -you can set CRYPT_LIB to point to the library name. -Perl will also build without des_fcrypt(), but the crypt() builtin will -fail at run time. - If you want build some core extensions statically into perl's dll, specify them in the STATIC_EXT macro. @@ -460,19 +391,18 @@ Be sure to read the instructions near the top of the makefiles carefully. Type "dmake" (or "nmake" if you are using that make). This should build everything. Specifically, it will create perl.exe, -perl512.dll at the perl toplevel, and various other extension dll's +perl514.dll at the perl toplevel, and various other extension dll's under the lib\auto directory. If the build fails for any reason, make sure you have done the previous steps correctly. =back -=head2 Testing Perl on Win32 +=head2 Testing Perl on Windows Type "dmake test" (or "nmake test"). This will run most of the tests from the testsuite (many tests will be skipped). -There should be no test failures when running under Windows NT/2000/XP. -Many tests I<will> fail under Windows 9x due to the inferior command shell. +There should be no test failures. Some test failures may occur if you use a command shell other than the native "cmd.exe", or if you are building from a path that contains @@ -485,7 +415,7 @@ If you're using the Borland compiler, you may see a failure in op/taint.t arising from the inability to find the Borland Runtime DLLs on the system default path. You will need to copy the DLLs reported by the messages from where Borland chose to install it, into the Windows system directory -(usually somewhere like C:\WINNT\SYSTEM32) and rerun the test. +(usually somewhere like C:\WINDOWS\SYSTEM32) and rerun the test. If you're using Borland compiler versions 5.2 and below, you may run into problems finding the correct header files when building extensions. For @@ -507,7 +437,7 @@ avoid these errors. Please report any other failures as described under L<BUGS AND CAVEATS>. -=head2 Installation of Perl on Win32 +=head2 Installation of Perl on Windows Type "dmake install" (or "nmake install"). This will put the newly built perl and the libraries under whatever C<INST_TOP> points to in the @@ -527,7 +457,7 @@ C<$INST_TOP\$INST_VER\bin\$ARCHNAME>, e.g. set PATH=c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH% -=head2 Usage Hints for Perl on Win32 +=head2 Usage Hints for Perl on Windows =over 4 @@ -561,7 +491,7 @@ following entries (of type REG_SZ or REG_EXPAND_SZ) may be set: Note the C<$]> in the above is not literal. Substitute whatever version of perl you want to honor that entry, e.g. C<5.6.0>. Paths must be -separated with semicolons, as usual on win32. +separated with semicolons, as usual on Windows. =item File Globbing @@ -581,12 +511,11 @@ with what Windows offers by way of a command shell. The crucial thing to understand about the Windows environment is that the command line you type in is processed twice before Perl sees it. -First, your command shell (usually CMD.EXE on Windows NT, and -COMMAND.COM on Windows 9x) preprocesses the command line, to handle -redirection, environment variable expansion, and location of the -executable to run. Then, the perl executable splits the remaining -command line into individual arguments, using the C runtime library -upon which Perl was built. +First, your command shell (usually CMD.EXE) preprocesses the command +line, to handle redirection, environment variable expansion, and +location of the executable to run. Then, the perl executable splits +the remaining command line into individual arguments, using the +C runtime library upon which Perl was built. It is particularly important to note that neither the shell nor the C runtime do any wildcard expansions of command-line arguments (so @@ -596,7 +525,7 @@ using a non-standard shell, be inconsistent). The only (useful) quote character is the double quote ("). It can be used to protect spaces and other special characters in arguments. -The Windows NT documentation has almost no description of how the +The Windows documentation has almost no description of how the quoting rules are implemented, but here are some general observations based on experiments: The C runtime breaks arguments at spaces and passes them to programs in argc/argv. Double quotes can be used to @@ -655,7 +584,7 @@ Discovering the usefulness of the "command.com" shell on Windows 9x is left as an exercise to the reader :) One particularly pernicious problem with the 4NT command shell for -Windows NT is that it (nearly) always treats a % character as indicating +Windows is that it (nearly) always treats a % character as indicating that environment variable expansion is needed. Under this shell, it is therefore important to always double any % characters which you want Perl to see (for example, for hash variables), even when they are @@ -665,11 +594,11 @@ quoted. The Comprehensive Perl Archive Network (CPAN) offers a wealth of extensions, some of which require a C compiler to build. -Look in http://www.cpan.org/ for more information on CPAN. +Look in L<http://www.cpan.org/> for more information on CPAN. Note that not all of the extensions available from CPAN may work -in the Win32 environment; you should check the information at -http://testers.cpan.org/ before investing too much effort into +in the Windows environment; you should check the information at +L<http://testers.cpan.org/> before investing too much effort into porting modules that don't readily build. Most extensions (whether they require a C compiler or not) can @@ -690,12 +619,12 @@ ensure Config.pm knows about it. If you don't have nmake, you can either get dmake from the location mentioned earlier or get an old version of nmake reportedly available from: - http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe +L<http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe> Another option is to use the make written in Perl, available from CPAN. - http://www.cpan.org/modules/by-module/Make/ +L<http://www.cpan.org/modules/by-module/Make/> You may also use dmake. See L</"Make"> above on how to get it. @@ -774,27 +703,6 @@ binary will always expand unquoted command lines, which may not be what you want if you use a shell that does that for you. The expansion done is also somewhat less powerful than the approach suggested above. -=item Win32 Specific Extensions - -A number of extensions specific to the Win32 platform are available -from CPAN. You may find that many of these extensions are meant to -be used under the Activeware port of Perl, which used to be the only -native port for the Win32 platform. Since the Activeware port does not -have adequate support for Perl's extension building tools, these -extensions typically do not support those tools either and, therefore, -cannot be built using the generic steps shown in the previous section. - -To ensure smooth transitioning of existing code that uses the -ActiveState port, there is a bundle of Win32 extensions that contains -all of the ActiveState extensions and several other Win32 extensions from -CPAN in source form, along with many added bugfixes, and with MakeMaker -support. The latest version of this bundle is available at: - - http://search.cpan.org/dist/libwin32/ - -See the README in that distribution for building and installation -instructions. - =item Notes on 64-bit Windows Windows .NET Server supports the LLP64 data model on the Intel Itanium @@ -842,23 +750,22 @@ Embedding Perl inside a 64-bit application. Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to indicate to the OS that it should execute the file using perl. -Win32 has no comparable means to indicate arbitrary files are +Windows has no comparable means to indicate arbitrary files are executables. Instead, all available methods to execute plain text files on -Win32 rely on the file "extension". There are three methods +Windows rely on the file "extension". There are three methods to use this to execute perl scripts: =over 8 =item 1 -There is a facility called "file extension associations" that will -work in Windows NT 4.0. This can be manipulated via the two -commands "assoc" and "ftype" that come standard with Windows NT -4.0. Type "ftype /?" for a complete example of how to set this -up for perl scripts (Say what? You thought Windows NT wasn't -perl-ready? :). +There is a facility called "file extension associations". This can be +manipulated via the two commands "assoc" and "ftype" that come +standard with Windows. Type "ftype /?" for a complete example of how +to set this up for perl scripts (Say what? You thought Windows +wasn't perl-ready? :). =item 2 @@ -894,7 +801,7 @@ avoids both problems is possible. A script called "runperl.bat" is available that can be copied to any filename (along with the .bat suffix). For example, if you call it "foo.bat", it will run the file "foo" when it is -executed. Since you can run batch files on Win32 platforms simply +executed. Since you can run batch files on Windows platforms simply by typing the name (without the extension), this effectively runs the file "foo", when you type either "foo" or "foo.bat". With this method, "foo.bat" can even be in a different location @@ -916,7 +823,7 @@ system. C<perldoc> is also a useful tool for browsing information contained in the documentation, especially in conjunction with a pager -like C<less> (recent versions of which have Win32 support). You may +like C<less> (recent versions of which have Windows support). You may have to set the PAGER environment variable to use a specific pager. "perldoc -f foo" will print information about the perl operator "foo". @@ -926,7 +833,7 @@ is assuming that Perl's normal behavior of opening a command-line window will go away. This isn't the case. If you want to start a copy of C<perl> without opening a command-line window, use the C<wperl> executable built during the installation process. Usage is exactly -the same as normal C<perl> on Win32, except that options like C<-h> +the same as normal C<perl> on Windows, except that options like C<-h> don't work (since they need a command-line window to print to). If you find bugs in perl, you can run C<perlbug> to create a @@ -957,21 +864,15 @@ that will be portable to other environments, see L<perlport> for a reasonably definitive list of these differences. Not all extensions available from CPAN may build or work properly -in the Win32 environment. See L</"Building Extensions">. +in the Windows environment. See L</"Building Extensions">. Most C<socket()> related calls are supported, but they may not behave as on Unix platforms. See L<perlport> for the full list. -Perl requires Winsock2 to be installed on the system. If you're -running Win95, you can download Winsock upgrade from here: - -http://www.microsoft.com/windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2/Default.asp - -Later OS versions already include Winsock2 support. Signal handling may not behave as on Unix platforms (where it doesn't exactly "behave", either :). For instance, calling C<die()> or C<exit()> from signal handlers will cause an exception, since most -implementations of C<signal()> on Win32 are severely crippled. +implementations of C<signal()> on Windows are severely crippled. Thus, signals may work only for simple things like setting a flag variable in the handler. Using signals under this port should currently be considered unsupported. @@ -997,7 +898,7 @@ of O'Reilly and Associates, Inc. Used with permission. =item Jan Dubois E<lt>jand@activestate.comE<gt> -=item Steve Hay E<lt>steve.hay@uk.radan.comE<gt> +=item Steve Hay E<lt>steve.m.hay@googlemail.comE<gt> =back @@ -1026,6 +927,6 @@ Win9x support was added in 5.6 (Benjamin Stuhl). Support for 64-bit Windows added in 5.8 (ActiveState Corp). -Last updated: 29 August 2007 +Last updated: 18 November 2010 =cut diff --git a/Master/tlpkg/tlperl/lib/pods/perlxs.pod b/Master/tlpkg/tlperl/lib/pods/perlxs.pod index 5f773bbac32..415f2ad2a00 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlxs.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlxs.pod @@ -74,7 +74,7 @@ See L<perlxstut> for a tutorial on the whole extension creation process. Note: For some extensions, Dave Beazley's SWIG system may provide a significantly more convenient mechanism for creating the extension -glue code. See http://www.swig.org/ for more information. +glue code. See L<http://www.swig.org/> for more information. =head2 On The Road @@ -1434,10 +1434,26 @@ The XS module can use INCLUDE: to pull that file into it. INCLUDE: Rpcb1.xsh If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then -the compiler will interpret the parameters as a command. +the compiler will interpret the parameters as a command. This feature is +mildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented +below. INCLUDE: cat Rpcb1.xsh | +Do not use this to run perl: C<INCLUDE: perl |> will run the perl that +happens to be the first in your path and not necessarily the same perl that is +used to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">. + +=head2 The INCLUDE_COMMAND: Keyword + +Runs the supplied command and includes its output into the current XS +document. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token +in that it runs the same perl interpreter that is running C<xsubpp>: + + INCLUDE_COMMAND: cat Rpcb1.xsh + + INCLUDE_COMMAND: $^X -e ... + =head2 The CASE: Keyword The CASE: keyword allows an XSUB to have multiple distinct parts with each diff --git a/Master/tlpkg/tlperl/lib/pods/perlxstut.pod b/Master/tlpkg/tlperl/lib/pods/perlxstut.pod index 62bef3b0c5f..91c13ed358f 100644 --- a/Master/tlpkg/tlperl/lib/pods/perlxstut.pod +++ b/Master/tlpkg/tlperl/lib/pods/perlxstut.pod @@ -198,14 +198,6 @@ been deleted): You can safely ignore the line about "prototyping behavior" - it is explained in L<perlxs/"The PROTOTYPES: Keyword">. -If you are on a Win32 system, and the build process fails with linker -errors for functions in the C library, check if your Perl is configured -to use PerlCRT (running B<perl -V:libc> should show you if this is the -case). If Perl is configured to use PerlCRT, you have to make sure -PerlCRT.lib is copied to the same location that msvcrt.lib lives in, -so that the compiler can find it on its own. msvcrt.lib is usually -found in the Visual C compiler's lib directory (e.g. C:/DevStudio/VC/lib). - Perl has its own special way of easily writing test scripts, but for this example only, we'll create our own test script. Create a file called hello that looks like this: @@ -228,7 +220,7 @@ and we should see the following output: =head2 EXAMPLE 2 Now let's add to our extension a subroutine that will take a single numeric -argument as input and return 0 if the number is even or 1 if the number +argument as input and return 1 if the number is even or 0 if the number is odd. Add the following to the end of Mytest.xs: @@ -732,7 +724,7 @@ description of an XSUB: Note that in contrast with L<"EXAMPLE 1">, L<"EXAMPLE 2"> and L<"EXAMPLE 3">, this description does not contain the actual I<code> for what is done -is done during a call to Perl function foo(). To understand what is going +during a call to Perl function foo(). To understand what is going on here, one can add a CODE section to this XSUB: double @@ -1023,8 +1015,8 @@ put these declarations on top.) This routine also returns a different number of arguments depending on the success or failure of the call to statfs. If there is an error, the error number is returned as a single-element array. If the call is successful, -then a 9-element array is returned. Since only one argument is passed into -this function, we need room on the stack to hold the 9 values which may be +then a 7-element array is returned. Since only one argument is passed into +this function, we need room on the stack to hold the 7 values which may be returned. We do this by using the PPCODE: directive, rather than the CODE: directive. @@ -1133,7 +1125,7 @@ And add the following code to Mytest.t, while incrementing the "11" tests to "13": $results = Mytest::multi_statfs([ '/', '/blech' ]); - ok( ref $results->[0]) ); + ok( ref $results->[0] ); ok( ! ref $results->[1] ); =head2 New Things in this Example @@ -1312,7 +1304,7 @@ layer. If it can't find one, it will call C<PerlIO_exportFILE()> to generate a new stdio C<FILE>. Please only call C<PerlIO_exportFILE()> if you want a I<new> C<FILE>. It will generate one on each call and push a new stdio layer. So don't call it repeatedly on the same -file. C<PerlIO()>_findFILE will retrieve the stdio layer once it has been +file. C<PerlIO_findFILE()> will retrieve the stdio layer once it has been generated by C<PerlIO_exportFILE()>. This applies to the perlio system only. For versions before 5.7, |